home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 9 / Night Owl CD-ROM (NOPV9) (Night Owl Publisher) (1993).ISO / 015a / clock344.zip / CLOCK.DOC < prev    next >
Text File  |  1993-03-09  |  186KB  |  5,083 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.                                         CLOCK
  26.  
  27.                                      Version 3.44
  28.  
  29.  
  30.  
  31.                             CLOCK is a shareware program.
  32.                      See Appendix A for registration information.
  33.                           $10 (or $25 for full source code)
  34.                                    Ronald Q. Smith
  35.                                   11 Black Oak Road
  36.                               North Oaks, MN 55127-6204
  37.  
  38.  
  39.  
  40.  
  41.  
  42.                        (c) Copyright 1991-1993 Ronald Q. Smith
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.           CLOCK Version 3.44                                  March 9, 1993
  75.  
  76.  
  77.                                        CONTENTS
  78.  
  79.  
  80.           1  INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . .   1
  81.  
  82.           1  CLOCK.SYS - Replacement Device Driver  . . . . . . . . . .   3
  83.                1.1  Unique Clock Hardware Support . . . . . . . . . . .   3
  84.                1.2  Installing CLOCK.SYS  . . . . . . . . . . . . . . .   4
  85.                1.3  Clock Type  . . . . . . . . . . . . . . . . . . . .   8
  86.                1.4  Examples  . . . . . . . . . . . . . . . . . . . . .  11
  87.                1.5  Future Enhancements . . . . . . . . . . . . . . . .  11
  88.  
  89.           2  CLK.EXE - Clock Control Program  . . . . . . . . . . . . .  12
  90.                2.1  CLK Command . . . . . . . . . . . . . . . . . . . .  12
  91.                2.2  Format of TZ= Function  . . . . . . . . . . . . . .  24
  92.                2.3  Using CLK . . . . . . . . . . . . . . . . . . . . .  27
  93.                2.4  Examples  . . . . . . . . . . . . . . . . . . . . .  30
  94.                2.5  Errors  . . . . . . . . . . . . . . . . . . . . . .  31
  95.                2.6  Future Enhancements . . . . . . . . . . . . . . . .  31
  96.  
  97.           3  CLKDEMO.EXE  . . . . . . . . . . . . . . . . . . . . . . .  32
  98.                3.1  CLKDEMO Command Line  . . . . . . . . . . . . . . .  32
  99.  
  100.           4  IOCTL - API TO CLOCK.SYS . . . . . . . . . . . . . . . . .  33
  101.                4.1  Data Structures . . . . . . . . . . . . . . . . . .  33
  102.                4.2  clksta  . . . . . . . . . . . . . . . . . . . . . .  36
  103.                4.3  setpw . . . . . . . . . . . . . . . . . . . . . . .  39
  104.                4.4  connec  . . . . . . . . . . . . . . . . . . . . . .  40
  105.                4.5  newpw . . . . . . . . . . . . . . . . . . . . . . .  42
  106.                4.6  rstrct  . . . . . . . . . . . . . . . . . . . . . .  43
  107.                4.7  stmode  . . . . . . . . . . . . . . . . . . . . . .  46
  108.                4.8  stzone  . . . . . . . . . . . . . . . . . . . . . .  47
  109.                4.9  tdisp . . . . . . . . . . . . . . . . . . . . . . .  50
  110.  
  111.           5  CLOCK.SYS - ASSEMBLY LANGUAGE API  . . . . . . . . . . . .  54
  112.                5.1  Opening the CLOCK$ Device . . . . . . . . . . . . .  54
  113.                5.2  Sending New Values to CLOCK.SYS . . . . . . . . . .  54
  114.                5.3  Getting Current Status of CLOCK.SYS . . . . . . . .  56
  115.  
  116.           APPENDIX A:  DEFINITION OF SHAREWARE  . . . . . . . . . . . .  57
  117.  
  118.           APPENDIX B:  CLOCK TYPES  . . . . . . . . . . . . . . . . . .  59
  119.                B.1  Type 0 - PC/AT  . . . . . . . . . . . . . . . . . .  59
  120.                B.2  Type 1 - Zenith Z-18x portables, Supersport 20  . .  60
  121.                B.3  Type 2 - Various Zenith Data System PCs.  . . . . .  60
  122.                B.4  Type 3 - Memory-Mapped Clocks . . . . . . . . . . .  61
  123.                B.5  Type 4 - Direct Register I/O Bus Clock  . . . . . .  62
  124.                B.6  Type 5 - Mitsubishi 8088 PCs  . . . . . . . . . . .  63
  125.  
  126.  
  127.                                           ii
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.           CLOCK Version 3.44                                  March 9, 1993
  141.  
  142.  
  143.                B.7  Type 6 - Indirect Register I/O Bus Clock  . . . . .  65
  144.                B.8  Type 7 - Complex I/O Bus Clock  . . . . . . . . . .  66
  145.                B.9  Type 8 - Generic I/O Bus Clock  . . . . . . . . . .  67
  146.                B.10 Type 9 - Quadram I/O Bus Clock  . . . . . . . . . .  67
  147.                B.11 Type A - AT&T 6300, 6300 PLUS, 6300 WGS . . . . . .  68
  148.                B.12 Type B - Hyundai 8088 clock . . . . . . . . . . . .  69
  149.  
  150.           APPENDIX C:  REVISION HISTORY . . . . . . . . . . . . . . . .  70
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.                                          iii
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.           CLOCK Version 3.44                                  March 9, 1993
  207.  
  208.  
  209.           1  INTRODUCTION
  210.  
  211.           CLOCK consists  of two programs  that give  you complete  control
  212.           over the operation of your calendar (battery-protected) clock and
  213.           your DOS/BIOS internal  timer.  The normal DOS  mode of operation
  214.           is  to read the calendar  clock when you boot  the system and set
  215.           the internal timer.  Thereafter all read operations refer only to
  216.           the internal timer  while time setting  operations write to  both
  217.           clocks.  In levels of DOS prior to 3.3,  even time setting opera-
  218.           tions only  wrote to  the internal  timer.  In  order to  set the
  219.           calendar clock you had to run the SETUP program.
  220.  
  221.           Some of the drawbacks  to the standard  DOS clock operation  that
  222.           the CLOCK programs address are:
  223.  
  224.                ∙    There  is no  provision  to switch  time zones  without
  225.                     resetting the system time.
  226.  
  227.                ∙    DOS does not handle automatic  changes between daylight
  228.                     savings time and standard time.
  229.  
  230.                ∙    The DOS/BIOS internal timer  often drifts quite rapidly
  231.                     away  from the  time  maintained by  the more  accurate
  232.                     calendar clock.
  233.  
  234.                ∙    Even  the calendar  clock drifts  slowly away  from the
  235.                     accurate time.   DOS  provides no way  to automatically
  236.                     adjust for that drift.
  237.  
  238.                ∙    If your  battery is failing  or some other  hardware or
  239.                     software problem  messes up  the time in  your calendar
  240.                     clock, there is no way to detect that except by manual-
  241.                     ly displaying the time and checking it.
  242.  
  243.                ∙    If you have to run a program that occasionally  changes
  244.                     the time incorrectly, there  is no way to protect  your
  245.                     clock  from those  changes.   You  can  also have  this
  246.                     problem  if  you are  a parent  whose children  set the
  247.                     clock when you don't want them to, an  instructor whose
  248.                     students  reset the time, or an expert young user whose
  249.                     parents mess up your clock.
  250.  
  251.                ∙    If you need to experiment with special  times and dates
  252.                     but don't want to have to reset your clock  afterwards,
  253.                     DOS has no mechanism to help.  In order to test end-of-
  254.                     month processing for your  application, you have to set
  255.                     the date  and time,  run your tests,  and then  set the
  256.                     time and date back.
  257.  
  258.  
  259.                                           1
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.           CLOCK Version 3.44                                  March 9, 1993
  273.  
  274.  
  275.                ∙    The standard DOS and BIOS software on some PCs can miss
  276.                     the change to  a new day  when the PC  is left on  over
  277.                     midnight.
  278.  
  279.                ∙    Your clock might  not handle automatic changes to a new
  280.                     year or may not understand leap years.
  281.  
  282.                ∙    You may have an  older PC from  before the PC/AT  clock
  283.                     standardization and your vendor no longer releases  new
  284.                     versions of DOS for that PC.   You are stuck on DOS 3.2
  285.                     or earlier or you have to give up your calendar clock.
  286.  
  287.  
  288.           If any of  those circumstances cause problems for  you, CLOCK can
  289.           help.  The  two primary programs are  CLOCK.SYS and CLK.EXE.   In
  290.           addition, if you are a software developer, CLKDEMO is provided in
  291.           source code to show you how to  program the extended clock opera-
  292.           tions into your own applications.
  293.  
  294.  
  295.                CLOCK.SYS is a clock device driver (CLOCK$ device).  It
  296.                replaces the DOS internal clock driver.  CLOCK.SYS pro-
  297.                vides  for automatic  time  zone conversion.   It  also
  298.                allows you to periodically or continuously get the time
  299.                from the  calendar clock.   This can  totally eliminate
  300.                problems with missing  day changes and realtime  clocks
  301.                that are  inaccurate.   CLOCK.SYS provides support  for
  302.                many  types of  calendar clocks  including many  of the
  303.                original add-in clocks of the 8088 era.  If your  clock
  304.                is not currently supported, I want to hear from you.  I
  305.                will be happy to add it to the software.
  306.               
  307.                CLK.EXE  is a  program  that allows  you to  separately
  308.                control your  DOS/BIOS internal clock  and battery-pro-
  309.                tected calendar clock.  Most importantly,  CLK.EXE will
  310.                handle time zones and will automatically switch between
  311.                standard and  daylight savings time  for you.   It also
  312.                supports automatic adjustment for calendar clock drift,
  313.                checks  for incorrect  or unlikely  times, and  can re-
  314.                strict time changes.
  315.  
  316.                CLKDEMO.EXE is a small part of CLK.EXE that is provided
  317.                in source code (C  language) form so  that you can  see
  318.                how to add clock control to your own applications.
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.                                           2
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.           CLOCK Version 3.44                                  March 9, 1993
  339.  
  340.  
  341.           1  CLOCK.SYS - Replacement Device Driver
  342.  
  343.           CLOCK.SYS is  a device driver  that replaces the  built-in CLOCK$
  344.           device driver in DOS levels 2.1  and above.  CLOCK.SYS adds  many
  345.           functions not provided  in the standard DOS CLOCK$ device driver.
  346.           You won't see mention of the DOS CLOCK$ device driver in your DOS
  347.           user's guides.   You will see a  very small mention of  it in the
  348.           system's  programmers reference  manuals if  you are  an assembly
  349.           language developer.   It  is there and  DOS was  specifically de-
  350.           signed to  let you replace  it with one  of your own  even if the
  351.           manual doesn't tell you that.
  352.  
  353.  
  354.           1.1  Unique Clock Hardware Support
  355.  
  356.           CLOCK.SYS  was originally  written  especially for  those  people
  357.           whose  clocks  are not  supported  by new  levels of  DOS.   This
  358.           usually occurs  because your vendor stopped  providing new levels
  359.           of DOS adapted  for your computer model.  Before  the days of the
  360.           PC/AT and standard clock interfaces, DOS was usually sold direct-
  361.           ly to  hardware vendors  who customized it  for their  system and
  362.           delivered it  with the system.   In  addition, many of  the early
  363.           clocks were provided by third-party, after-market vendors who had
  364.           no idea what system it would be used in.  Since those systems and
  365.           clocks have been  out of production for a long  time, most of the
  366.           vendors have stopped  providing upgrades.  Yet most  of those PCs
  367.           will happily run  DOS 3.3 or above and especially  DOS 5.0 except
  368.           that you have to give up your calendar clock.
  369.  
  370.           CLOCK.SYS supports a wide variety of different clock hardware and
  371.           BIOS interfaces.  As far as possible, CLOCK.SYS will automatical-
  372.           ly  determine what  clock interface  to  use.   If the  automatic
  373.           determination  does  not  work  for your  system,  you  may  tell
  374.           CLOCK.SYS specifically what interface type to use.   CLOCK.SYS is
  375.           also required  by anyone  who  wants to  use CLK  as it  provides
  376.           functions not  provided by the  normal DOS CLOCK$  device driver.
  377.           CLOCK.SYS is fully  compatible with the DOS device  driver on all
  378.           modern PCs and many older ones.
  379.  
  380.           If your PC clock is not currently supported but you would like to
  381.           remove the  restrictions on  what versions  of DOS  you can  use,
  382.           please  contact me by mail or on  CompuServe.  I will be happy to
  383.           add support for your  clock.  I will need some technical informa-
  384.           tion and help from you in getting it to work so I will give you a
  385.           $0 usage license for your help.   Please see section 1.3 for  the
  386.           current list of supported clocks and Appendix B for a description
  387.           of those clocks.
  388.  
  389.  
  390.  
  391.                                           3
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.           CLOCK Version 3.44                                  March 9, 1993
  405.  
  406.  
  407.           1.2  Installing CLOCK.SYS
  408.  
  409.           To install the  device driver include the following  line in your
  410.           CONFIG.SYS file.
  411.  
  412.           Syntax    device=[d:][path\]clock.sys [type][,io_addr] [/N]
  413.  
  414.                                           or
  415.  
  416.                     device=[d:][path\]clock.sys 3[,segment[,write0,
  417.                          write1,read]] [/N]
  418.  
  419.                                           or
  420.  
  421.                     device=[d:][path\]clock.sys A[,base_year] [/N]
  422.  
  423.  
  424.           Parameters     d:
  425.                          Identifies the drive containing CLOCK.SYS.   If d:
  426.                          is not provided, the boot drive is assumed.
  427.  
  428.                     path\
  429.                          Specifies the directory containing  CLOCK.SYS.  If
  430.                          path\ is not given, the root directory is assumed.
  431.  
  432.                     CLOCK.SYS
  433.                          Is the name of the CLOCK.SYS file.  You may change
  434.                          the name  if you  wish, but you  must not  use the
  435.                          .COM or .EXE extensions.
  436.  
  437.                     type
  438.                          Is the kind of calendar clock on your system.   If
  439.                          you do not provide type, CLOCK.SYS will probe your
  440.                          system   to  determine   which  clock   you  have.
  441.                          CLOCK.SYS is  usually able  to detect the  type of
  442.                          calendar clock  without trouble.  It  is possible,
  443.                          however, that you have some other hardware in your
  444.                          system that  could fool CLOCK.SYS.   For that rea-
  445.                          son, you might need to provide the type  of clock.
  446.                          See section  1.3 and Appendix B  for more informa-
  447.                          tion about the clock types.
  448.  
  449.                     io_addr
  450.                          Is  the I/O  bus address  of your  clock hardware.
  451.                          Some  of the  types of  clocks that  are supported
  452.                          were set  up at a  wide variety of  I/O addresses.
  453.                          CLOCK.SYS  probes  all the  commonly used  I/O ad-
  454.                          dresses for  these clocks.   However, you  or your
  455.  
  456.  
  457.                                           4
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.           CLOCK Version 3.44                                  March 9, 1993
  471.  
  472.  
  473.                          vendor may have installed your clock at an address
  474.                          that CLOCK.SYS  doesn't know about.   By providing
  475.                          the  address, you  make it  much more  likely that
  476.                          CLOCK.SYS will correctly find your clock.  Even if
  477.                          you  don't know what type  of clock you have, pro-
  478.                          viding the I/O address may be enough for CLOCK.SYS
  479.                          to determine which one it is.  io_addr is current-
  480.                          ly  used with clock  types 4, 6,  7, 8, 9,  and B.
  481.                          Normally this is 240, 2C0, or 340 for types 4,  6,
  482.                          and 7.  It is 210 or 310 for type 9.  And it is E0
  483.                          for type B.  All numbers are in hex.  For example,
  484.                          an AST Research clock might be:
  485.  
  486.                          device=[d:][path\]clock.sys 4,2C0
  487.  
  488.                          If  you do  not  specify the  "io_addr", CLOCK.SYS
  489.                          will try to determine the correct address by prob-
  490.                          ing.
  491.  
  492.                          If you are sure that you have an I/O clock but you
  493.                          are not sure  which one it is, specify  type 8 and
  494.                          supply the io_addr  if possible.  Type 8  does not
  495.                          represent a specific clock.  Rather it attempts to
  496.                          determine whether your clock is a type 4, 6, 7, 9,
  497.                          or  B using a  sequence of tests  similar to those
  498.                          used by some  of the I/O  clock vendors to  figure
  499.                          out what kind of clock you have.
  500.  
  501.                     If you  have a  memory mapped  clock, you  may use  the
  502.                     second format to specify the addresses to be used.   If
  503.                     you don't know the addresses, CLOCK.SYS will attempt to
  504.                     determine them by probing.
  505.  
  506.                     segment
  507.                          Is  the base  address  used to  access the  clock.
  508.                          Usually your  documentation will give  the segment
  509.                          address as four  hex digits such as  FE00 or F000.
  510.                          Some addresses may be less than four digits (e.g.,
  511.                          70).   Other  documentation may show  addresses in
  512.                          the  form aaaa:bbbb.    In this  case the  segment
  513.                          address is  the aaaa  value.  Sometimes  these ad-
  514.                          dresses  are written as  0xaaaa, aaaah,  aaaaH, or
  515.                          0Xaaaa.  In all of these forms there is a 2- to 4-
  516.                          digit hex number that is the segment address.
  517.  
  518.                     write0
  519.                          Is  the offset used to write 0 bits.  It must also
  520.                          be a hex  address and may be 0,  F002, or anything
  521.  
  522.  
  523.                                           5
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.           CLOCK Version 3.44                                  March 9, 1993
  537.  
  538.  
  539.                          else the vendor chose.  If the addresses are given
  540.                          in the aaaa:bbbb form,  use the bbbb.   With these
  541.                          clocks, you  read and  write the clock  by reading
  542.                          the  memory addresses.   For example,  reading ad-
  543.                          dress segment:write0 results in writing a zero bit
  544.                          to the  clock.  Writing an  appropriate length se-
  545.                          quence of zero and one bits sets the clock.
  546.  
  547.                     write1
  548.                          Is the offset used to write 1 bits.
  549.  
  550.                     read
  551.                          Is the offset used to read bits.
  552.  
  553.                          If your  documentation gives  the segment  address
  554.                          but isn't  clear about the  offsets, just  specify
  555.                          the  segment address  and CLOCK.SYS  will try  all
  556.                          offset combinations that it knows about.
  557.  
  558.                          If you specify one of the offsets, you must speci-
  559.                          fy them all.
  560.  
  561.                     The third format is used with the AT&T 6300 clocks.
  562.  
  563.                     base_year
  564.                          Is used for the AT&T 6300 clocks (type=A).   Dates
  565.                          prior to that year or more than 7 years after that
  566.                          year will  not be handled  correctly.  If  no base
  567.                          year is specified, 1992  will be used.   Dates be-
  568.                          tween the start of  the base year  and the end  of
  569.                          the seventh year later are handled (e.g., 1992-1-1
  570.                          until 1999-12-31).
  571.  
  572.                     /N
  573.                          Indicates that  you do  not want CLOCK.SYS  to at-
  574.                          tempt  to detect  missed date  changes.   Normally
  575.                          CLOCK.SYS  will  try to  detect  when  a date  has
  576.                          changed that was not  reported by the BIOS.   This
  577.                          usually happens  when a  program  is running  past
  578.                          midnight and calls the BIOS to read the time rath-
  579.                          er than calling  DOS.  That program sees the date-
  580.                          change  indication   from   the   BIOS   and   DOS
  581.                          (CLOCK.SYS) never gets a chance to change the day.
  582.                          However,  the logic  that  CLOCK.SYS uses  can  be
  583.                          fooled by  programs that change the  time with di-
  584.                          rect calls  on the BIOS  and may advance  the date
  585.                          incorrectly.  This is very rare,  but if your date
  586.  
  587.  
  588.  
  589.                                           6
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.           CLOCK Version 3.44                                  March 9, 1993
  603.  
  604.  
  605.                          advances unexpectedly or by more than one day, you
  606.                          may want to use this option.
  607.  
  608.           Notes     DOS interfaces                    ______________
  609.                     All DOS  DATE and  TIME commands and  all DOS  date and
  610.                     time system calls will  operate with no apparent change
  611.                     to you  or any program.   Unless you  have used  CLK to
  612.                     change the time handling,  your clocks are handled just
  613.                     as DOS would handle them.
  614.  
  615.                     Dates and leap years                    ____________________
  616.                     CLOCK.SYS supports all valid DOS dates from 1980-1-1 to
  617.                     2079-12-31.   It supports dates to  2099-12-31 for many
  618.                     of the clocks.  CLOCK.SYS also handles year changes and
  619.                     leap years automatically for  clock types that don't do
  620.                     it themselves.
  621.  
  622.                     Time zones and daylight savings time                    ____________________________________
  623.                     CLOCK.SYS in conjunction  with CLK.EXE provides support
  624.                     for multiple  time zones  and automatic conversion  be-
  625.                     tween daylight  savings time  and standard time  at the
  626.                     appropriate  times  of  the  year.   For  this  reason,
  627.                     CLOCK.SYS  may be  of great  use  to you  even if  your
  628.                     version of DOS already supports your clock correctly.
  629.  
  630.                     Clock synchronization                    _____________________
  631.                     Normally,  CLOCK.SYS operates  identically  to the  DOS
  632.                     CLOCK$ device driver.   At boot it  sets the DOS  clock
  633.                     from the calendar clock.  Any time you change the  date
  634.                     or time it writes to both clocks.
  635.  
  636.                     With CLK.EXE you  have several other  options.  If  you
  637.                     have  specified a  time zone  and offset  with CLK.EXE,
  638.                     CLOCK.SYS will  adjust all times read  from and written
  639.                     to the calendar clock by the time zone offset.  You can
  640.                     also set it to read the calendar clock rather than  the
  641.                     DOS  clock for  some  or all  time  requests to  ensure
  642.                     continued synchronization  of the two clocks.   You can
  643.                     also  totally separate the two clocks  so that DOS time
  644.                     and  date functions  only read  and write  the DOS/BIOS
  645.                     internal clock.
  646.  
  647.                     Time setting limits                    ___________________
  648.                     CLK.EXE can tell CLOCK.SYS to apply limits to the  time
  649.                     changes  that it  will  accept or  stop accepting  time
  650.                     changes at all.  For example, you can tell CLOCK.SYS to
  651.                     accept no  changes that  would set the  clock backward.
  652.                     You can also inhibit all changes.
  653.  
  654.  
  655.                                           7
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.           CLOCK Version 3.44                                  March 9, 1993
  669.  
  670.  
  671.                     Password Protection                    ___________________
  672.                     CLK.EXE  can establish  a  password to  control  future
  673.                     changes to the time  zone, connection, and time setting
  674.                     limits.   Once  the password  is  set, all  attempts to
  675.                     change those  values will simply be  ignored unless the
  676.                     correct  password  is supplied.    You  may change  the
  677.                     daylight  versus standard time  flag and the continuous
  678.                     time display without knowing the password.
  679.  
  680.                     Continuous Time Display                    _______________________
  681.                     CLK.EXE can tell CLOCK.SYS to display the time continu-
  682.                     ously at any position on your screen.  You specify  the
  683.                     cursor coordinates, display  attributes, and 12-hour or
  684.                     24-hour mode  and  CLOCK.SYS will  update  the  display
  685.                     every second.
  686.  
  687.                     Saving Settings Across Boots                    ____________________________
  688.                     With  CLK.EXE  you  can   save  the  current  state  of
  689.                     CLOCK.SYS  at any time  in a form  that can be  used on
  690.                     your next boot.  You can set up your time zone, setting
  691.                     limits, connection mode, continuous display, and  pass-
  692.                     word and then save  a new version  of CLOCK.SYS.   This
  693.                     new  version  will  automatically  start  running  with
  694.                     without having to scan for your clock type and with all
  695.                     your standard state automatically in effect.
  696.  
  697.  
  698.           1.3  Clock Type
  699.  
  700.           There  are almost as many different  implementations of PC clocks
  701.           as there are different types of PCs.  Until the PC/AT came along,
  702.           there  was no standard for  battery-protected clocks, and each PC
  703.           and add-in vendor was likely to implement them differently.  With
  704.           the PC/AT a standard and documented interface for such clocks was
  705.           provided.   Since that  time, most  PCs have  followed the  PC/AT
  706.           standard.   It is  earlier PCs, especially  8088 PCs,  that don't
  707.           follow the standard.  Since these  are early PCs, there is also a
  708.           high probability that the vendor is  no longer providing modified
  709.           versions of  DOS with  built-in support for  their clocks.   Most
  710.           add-in clock vendors never did provide a modified DOS and you had
  711.           to manage  your clock  with utility  programs.   This leaves  you
  712.           faced with the choice  between staying with  an early version  of
  713.           DOS or giving up your clock.
  714.  
  715.           CLOCK.SYS is  intended to  free you from  those limitations.   It
  716.           will work with  all versions of  DOS from 2.10  through 5.00  and
  717.           undoubtedly beyond.  It  also attempts to automatically determine
  718.           what kind of clock you have  and install the correct support  for
  719.  
  720.  
  721.                                           8
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.           CLOCK Version 3.44                                  March 9, 1993
  735.  
  736.  
  737.           it.  However, there are often enough differences between PCs that
  738.           the automatic determination  may not  find anything  or may  even
  739.           make  the wrong choice.   To give you more  control of the situa-
  740.           tion, you may specify the clock interface by giving an  interface
  741.           number.
  742.  
  743.           It will  not always be  easy to decide  what interface  number to
  744.           use.  You will  at least need  some technical information on  how
  745.           your  clock works or on  the BIOS calls used  to control the bat-
  746.           tery-protected clock.  If you find a description below that seems
  747.           to  match, give it a try.  The  most that should go wrong is that
  748.           your time and date will be set incorrectly,  but then they proba-
  749.           bly weren't working anyhow.
  750.  
  751.           If you aren't sure what interface to use or if you are  sure that
  752.           your clock is not  supported, LET ME KNOW.  I WOULD LIKE TO HELP.
  753.           You can help me make CLOCK.SYS better for everyone.  I would even
  754.           like to  hear from you  if CLOCK.SYS  did work  for you and  your
  755.           clock isn't  currently listed.   I would like  to be able  to add
  756.           your PC manufacturer and  model number to  the supported list  so
  757.           others know what to use.  If CLOCK.SYS did not work for you, I am
  758.           interested in  making the changes so  that it does work.   If you
  759.           can  provide me with the  necessary technical information, I will
  760.           make the changes.
  761.  
  762.           Usually,  a technical  reference  manual with  hardware and  BIOS
  763.           interfaces is the best source.  Even if you  don't have one, your
  764.           original  hardware  vendor may  be  willing  to send  you  enough
  765.           information  to allow  you  to program  the clock.   If  all else
  766.           fails, we may even  be able to use an old copy of  DOS or a clock
  767.           setting utility to  figure out how it works.   Before we do that,
  768.           check  your license to be sure that it is not forbidden to disas-
  769.           semble the software to see how the clock works.  
  770.           The following table shows the  systems that have been  determined
  771.           to  work with existing  clock types.   If your  system is  in the
  772.           list,  try the clock type indicated.  If not, look through Appen-
  773.           dix B which tells you about  the characteristics of each type  of
  774.           clock and see if anything seems to match your system type.
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.                                           9
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.           CLOCK Version 3.44                                  March 9, 1993
  801.  
  802.  
  803.                    ╔═══════════════════════════╤══════════════════════════╗
  804.                    ║     SYSTEM                │  BLOCK TYPE              ║
  805.                    ╟───────────────────────────┼──────────────────────────╢
  806.                    ║     Amstrad PC1521DD      │  0                       ║
  807.                    ╟───────────────────────────┼──────────────────────────╢
  808.                    ║     AST Research          │  8 (4, 6, or 7) See dis- ║
  809.                    ║       Six-Pack            │  cussion above and in    ║
  810.                    ║       I/O Plus            │  Appendix B              ║
  811.                    ║       etc.                │                          ║
  812.                    ╟───────────────────────────┼──────────────────────────╢
  813.                    ║     AT&T 6300             │  A                       ║
  814.                    ╟───────────────────────────┼──────────────────────────╢
  815.                    ║     Hyundai 8088          │  B                       ║
  816.                    ╟───────────────────────────┼──────────────────────────╢
  817.                    ║     IBM PC/AT and most    │  0                       ║
  818.                    ║     PCs since then.       │                          ║
  819.                    ╟───────────────────────────┼──────────────────────────╢
  820.                    ║     Leading Edge Model D  │  5                       ║
  821.                    ╟───────────────────────────┼──────────────────────────╢
  822.                    ║     Mitsubishi 8088       │  5                       ║
  823.                    ╟───────────────────────────┼──────────────────────────╢
  824.                    ║     Quadram Corp.         │  9                       ║
  825.                    ║       QuadCard            │                          ║
  826.                    ║       QuadCard II         │                          ║
  827.                    ║       QuadCard 512+       │                          ║
  828.                    ╟───────────────────────────┼──────────────────────────╢
  829.                    ║     SMT No-Slot Clock     │  3                       ║
  830.                    ╟───────────────────────────┼──────────────────────────╢
  831.                    ║     Sperry PC-1           │  5                       ║
  832.                    ╟───────────────────────────┼──────────────────────────╢
  833.                    ║     Sperry PC/HT          │  5                       ║
  834.                    ╟───────────────────────────┼──────────────────────────╢
  835.                    ║     Tandy 1200HD          │  4                       ║
  836.                    ╟───────────────────────────┼──────────────────────────╢
  837.                    ║     Vendex Turbo-888-XT   │  4                       ║
  838.                    ╟───────────────────────────┼──────────────────────────╢
  839.                    ║     Zenith Supersport 20  │  1                       ║
  840.                    ╟───────────────────────────┼──────────────────────────╢
  841.                    ║     Zenith Z-18x          │  1                       ║
  842.                    ╚═══════════════════════════╧══════════════════════════╝
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.                                           10
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.           CLOCK Version 3.44                                  March 9, 1993
  867.  
  868.  
  869.           1.4  Examples
  870.  
  871.           For almost everyone, the only format you ever need to use is:
  872.                device=[d:][path\]clock.sys
  873.  
  874.           If CLOCK.SYS is in  the root directory of your boot  device, this
  875.           is:
  876.                device=clock.sys
  877.  
  878.           CLOCK.SYS will  quite happily load  into the upper  memory blocks
  879.           (UMBs)  provided by DOS 5.0 and by other software.  With DOS 5.0,
  880.           you might use:
  881.                devicehigh=clock.sys
  882.  
  883.           With some memory managers you can even load CLOCK.SYS into  upper
  884.           memory blocks on earlier levels of  DOS.  See your manual for the
  885.           commands to use.  Some of these  memory managers will create UMBs
  886.           on 8088  and 80286 systems.   CLOCK.SYS  loads and  runs high  on
  887.           those systems as well.
  888.  
  889.           With a memory mapped clock that uses an address combination  that
  890.           CLOCK.SYS doesn't search automatically  and with CLOCK.SYS stored
  891.           in the C:\UTILITY directory, you might use:
  892.                device=c:\utility\clock.sys 3,ffff,f000,f004,f008
  893.           Please note that the memory addresses chosen for this example are
  894.           not likely to match those of your clock and you should substitute
  895.           the addresses appropriate to your clock.
  896.  
  897.           If you have an  I/O clock with the same interface  as the Quadram
  898.           Corp. clock but a different I/O address, you might use:
  899.                device=clock.sys 9,3fc
  900.           if your I/O base address were 3fc.
  901.  
  902.           If you have one of the AT&T 6300 system types and you occasional-
  903.           ly need to set your clock prior to 1992-1-1, you might use:
  904.                device=clock.sys a,1988
  905.  
  906.           1.5  Future Enhancements
  907.  
  908.           Of course,  I hope  to add  more clocks as  people ask  for them.
  909.           Those old PCs are still good for a lot of what we do even if they
  910.           are sometimes relegated to a secondary status.
  911.  
  912.           There are no other outstanding enhancements currently planned for
  913.           CLOCK.SYS.
  914.  
  915.  
  916.  
  917.  
  918.  
  919.                                           11
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.           CLOCK Version 3.44                                  March 9, 1993
  933.  
  934.  
  935.           2  CLK.EXE - Clock Control Program
  936.  
  937.           CLK gives you complete control over the operation of the calendar
  938.           clock and  DOS/BIOS clock.   You can  operate them  separately or
  939.           together.  You  can establish time  zones, daylight savings  time
  940.           rules, automatic adjustment, synchronization rules, and more.
  941.  
  942.  
  943.           2.1  CLK Command
  944.  
  945.           Syntax    clk [function] [function ...] [/I[file]] [/?]
  946.  
  947.                               or in full form
  948.  
  949.                     clk [A=±sss.cc] [C=A|D|R|W] [D=[N][x,y,a[,12|,24]]
  950.                          [L=...] [M=...] [R=A|B-hh:mm:ss|F+hh:mm:ss|N|R]
  951.                          [S=C|D]    [TZ=...]    [W=-back,+forward]     [/B]
  952.                          [/I[file][,C]]  [/M[file][,C]] [/P[N]]  [/S[file]]
  953.                          [/?]
  954.  
  955.           Parameters     function
  956.                          There  are many  functions that  may be  used with
  957.                          CLK.EXE and  they are discussed  in the  following
  958.                          paragraphs.   You may use any  number of functions
  959.                          on  a single command  line and  they will  be pro-
  960.                          cessed  in  the order  in  which  you enter  them.
  961.                          However, if  any error is discovered in any of the
  962.                          functions, none of them are processed.  Thus, 
  963.                               clk c=r tz=:est
  964.                          is the same as the two command lines:
  965.                               clk c=r
  966.                               clk tz=:est
  967.                          except that an error in either of the functions in
  968.                          the first  example cause  the whole command  to be
  969.                          ignored.
  970.  
  971.                          The case (upper  or lower) of any  of the function
  972.                          names, options,  or values  is ignored  except for
  973.                          the TZ  function's time  zone names.   Even there,
  974.                          the case is not used.  It is simply preserved  for
  975.                          later display.
  976.  
  977.                          You can display a  help message about any function
  978.                          or option  by immediately  following the  function
  979.                          letter or  option letter with ?.  Thus M? displays
  980.                          help about  the M= function and  /I? displays help
  981.                          about the I  option.  /?  displays a help  message
  982.                          about the CLK command line.
  983.  
  984.  
  985.                                           12
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.           CLOCK Version 3.44                                  March 9, 1993
  999.  
  1000.  
  1001.                     none
  1002.                          If no function or option is provided, CLK displays
  1003.                          the current  state of  operation of  CLOCK.SYS and
  1004.                          the current time from  both the calendar clock and
  1005.                          the DOS/BIOS clock.
  1006.  
  1007.                          If you have used CLK to set a time  zone (TZ func-
  1008.                          tion), the current time zone name and offset value
  1009.                          are  displayed.     These  values   are  saved  in
  1010.                          CLOCK.SYS so that they may  be used for time func-
  1011.                          tions.
  1012.  
  1013.                          The connection state of the clocks (C function) is
  1014.                          displayed as is the current restrictions  (R func-
  1015.                          tion) on clock changes.
  1016.  
  1017.                          All uses  of CLK  (except  errors and  /?) end  by
  1018.                          displaying  the same information.  You always know
  1019.                          the state of your two clocks after execution.
  1020.  
  1021.                     A=±sss.cc
  1022.                          The Adjust function is used to set a daily adjust-
  1023.                          ment factor in seconds and 100ths of seconds.
  1024.  
  1025.                          This function assumes that you have some knowledge
  1026.                          of the  rate at  which your calendar  clock drifts
  1027.                          with respect to "real"  time.  Presumably you have
  1028.                          periodically  set your clock  using a program that
  1029.                          calls the Naval Observatory  or NIST and noted the
  1030.                          difference  over time.    Some such  programs will
  1031.                          help you to calculate the drift rate.  You can get
  1032.                          a very good adjustment from a decent quartz watch.
  1033.  
  1034.                          The value may be a positive or  negative number in
  1035.                          the range  -326.99 to +326.99 seconds  per day but
  1036.                          reasonable values are likely to be a fraction of a
  1037.                          second.
  1038.  
  1039.                          The first time  you use A=, your clock  is not ad-
  1040.                          justed.  The  value of A and the  current time are
  1041.                          saved in  a file  for later  use.   Later you  can
  1042.                          choose to run CLK with the /I option to invoke the
  1043.                          file.  The elapsed  time since the last adjustment
  1044.                          (or the time you last changed A) in days and frac-
  1045.                          tions is multiplied by  A to calculate any adjust-
  1046.                          ment that needs to be applied.  Only whole seconds
  1047.                          of adjustment are applied.
  1048.  
  1049.  
  1050.  
  1051.                                           13
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.           CLOCK Version 3.44                                  March 9, 1993
  1065.  
  1066.  
  1067.                          The A=  function only sets the  adjustment factor.
  1068.                          The  actual adjustment  is carried  out by  the L=
  1069.                          function.   You don't have  to enter the  L= func-
  1070.                          tion.  CLK will do that for you the first time you
  1071.                          use A=  and will keep  it up  to date as  it later
  1072.                          makes adjustments.
  1073.  
  1074.                          NOTE:  Do not  use the A=  function with the  AT&T
  1075.                          6300 clocks  (Type A) or the  Quadram clocks (Type
  1076.                          9).  They only  permit the time to  be set to  the
  1077.                          nearest minute.
  1078.  
  1079.                     C=A
  1080.                          Connects the  two clocks for All  operations.  All
  1081.                          read operations go directly to the calendar clock.
  1082.                          The calendard clock is  read, the time is adjusted
  1083.                          for any time zone offset, and the adjusted time is
  1084.                          written to the DOS clock and returned to the call-
  1085.                          er.   With this function, your  calendar clock es-
  1086.                          sentially becomes  the only  clock.  However,  the
  1087.                          DOS clock is set each time so that any application
  1088.                          reading the clock  directly (without going through
  1089.                          DOS) sees the  same time that DOS reports.   It is
  1090.                          unwise to use this function  if your clock is slow
  1091.                          (some I/O clocks and some memory-mapped clocks) or
  1092.                          if it  only increments  in units of  seconds (most
  1093.                          clocks).  Any time zone offset is applied to reads
  1094.                          and writes.
  1095.  
  1096.                     C=D
  1097.                          Disconnects  the two  clocks.   Any change  of the
  1098.                          date  and time  will  affect the  DOS clock  only.
  1099.                          Reads also use the DOS  clock only.  This function
  1100.                          allows you  to perform  any operation on  the time
  1101.                          without affecting  your  calendar clock.    It  is
  1102.                          useful for dealing with ill-behaved programs  that
  1103.                          need to  change the time and  for testing programs
  1104.                          at different dates and  times.  You can  later use
  1105.                          the C=R, C=A,  or other functions  to re-establish
  1106.                          the  value in  your  DOS clock  from the  calendar
  1107.                          clock.
  1108.  
  1109.                     C=R
  1110.                          Connects the  two clocks for  writing and periodic
  1111.                          Reading.   This  function  may be  used when  your
  1112.                          clocks  drift slowly  with respect to  each other.
  1113.                          If the time has  not been read  for about 10  sec-
  1114.                          onds, the calendar clock will be read, adjusted by
  1115.  
  1116.  
  1117.                                           14
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.           CLOCK Version 3.44                                  March 9, 1993
  1131.  
  1132.  
  1133.                          the offset  if any, and the  adjusted time written
  1134.                          to the DOS clock and returned to the caller.  This
  1135.                          periodic Read  assures you  that the  clocks never
  1136.                          get  very  far out  of  synchronization with  each
  1137.                          other.    Some calendar  clocks take  a relatively
  1138.                          long time  to read and  most don't have  100ths of
  1139.                          seconds.  By only  reading the calendar clock when
  1140.                          no other time request has occurred in the last  10
  1141.                          seconds,  we minimize  both  the overhead  and any
  1142.                          visibility of time jumps.
  1143.  
  1144.                     C=W
  1145.                          Connects  the two clocks for Writing.  This is the
  1146.                          default  mode of  operation and  is the  same mode
  1147.                          that the DOS CLOCK$  device driver supports as its
  1148.                          only mode.  Reading the time is served by the  DOS
  1149.                          clock.  Writing  the time sets both clocks.   If a
  1150.                          time zone  offset has  previously been  specified,
  1151.                          all writes to  the clock are adjusted  so that the
  1152.                          calendar  clock remains  on  the base  time.   For
  1153.                          example,  if the calendar clock is  set to UTC and
  1154.                          you specify that you want to use CST which has  an
  1155.                          offset of 6 hours from UTC, all writes of the time
  1156.                          will have 6 hours added  to them before writing to
  1157.                          the  calendar clock.   Thus the DOS  clock and the
  1158.                          calendar clock remain at a constant time offset.
  1159.  
  1160.                     D=N
  1161.                          The D=  function controls  a continuous  time dis-
  1162.                          play.  D=N turns off the continuous display.
  1163.  
  1164.                     D=x,y,a[,12|,24]
  1165.                          Starts a continuous  time display at cursor  posi-
  1166.                          tion x,y  with display attribute a.   Cursor posi-
  1167.                          tion 0,0  is the upper left corner  of the screen.
  1168.                          The typical screen format  runs from 0,0 to 79,24.
  1169.                          The display  attribute is a  two-digit hex  number
  1170.                          that gives the  background and foreground  colors.
  1171.                          The high-order digit is the background color (0 to
  1172.                          7 usually)  and the  low-order digit is  the fore-
  1173.                          ground  or character color (0  to F).  The default
  1174.                          display is  a 24-hour clock in  the form HH:MM:SS.
  1175.                          If you add  the ",12", the display will  use a 12-
  1176.                          hour clock.  No AM or PM indication is given.
  1177.  
  1178.                          D=72,24,79,12  will place the display at the right
  1179.                          edge of the  last line of most screens.   The text
  1180.  
  1181.  
  1182.  
  1183.                                           15
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.           CLOCK Version 3.44                                  March 9, 1993
  1197.  
  1198.  
  1199.                          will be in  bright blue on a  white background and
  1200.                          the hours will run from 12 through 11.
  1201.  
  1202.                          The  D= functions  should not  be  used if  CLK is
  1203.                          executed from within  Windows.  If  you try to  do
  1204.                          so,  you will  received  an error  message.   This
  1205.                          avoids  a hung  system  which would  occur if  CLK
  1206.                          didn't check.
  1207.  
  1208.                     L=YYYY-MM-DD,hh:mm:ss,±sss.cc
  1209.  
  1210.                          The L= function is not intended to be used on  the
  1211.                          command line, but will  be accepted if you provide
  1212.                          it.  The  L= function is  normally created by  CLK
  1213.                          and saved  in the  CLK.INI file  for later  use in
  1214.                          processing adjustments.  The  date and time of the
  1215.                          last adjustment (or the  most recent time you gave
  1216.                          an A= function on  the command line) are given  by
  1217.                          the YYYY-MM-DD,hh:mm:ss.   Any non-digit  except a
  1218.                          space may  separate the sub-fields.   The date and
  1219.                          time  must be followed by a  comma and any adjust-
  1220.                          ment remainder.   The  adjustment remainder  is in
  1221.                          the same form as the value for the A= function but
  1222.                          will usually be a fraction of a second.  It is the
  1223.                          adjustment  that was  left over  the last  time an
  1224.                          adjustment  was  actually  made  since only  whole
  1225.                          seconds of changes are made to the clock.
  1226.  
  1227.                          The L= function triggers  an adjustment if needed.
  1228.                          Generally,  it will  follow  the A=  function that
  1229.                          sets the  adjustment factor.  Both  of these func-
  1230.                          tions normally appear in the CLK.INI file.
  1231.  
  1232.                          The L= function  may also be used by  itself to do
  1233.                          simple arithmetic on  the clocks.   Use it on  the
  1234.                          command line with any earlier date and time and an
  1235.                          adjustment of  the number of  seconds (positive or
  1236.                          negative) that you want  added to the clock.   The
  1237.                          change will  be made and the  last adjustment time
  1238.                          set to the current time.  For example, 
  1239.                               clk l=1990-1-1,0:0:0,-4
  1240.                          will subtract 4 seconds from the clocks.
  1241.  
  1242.                     M=±sss.cc,YYYY-MM-DD,hh:mm:ss
  1243.                          The M=  function is used to help you calculate the
  1244.                          automatic  adjustment A=  value for  your calendar
  1245.                          clock.  The M= function is used to enter the manu-
  1246.                          al adjustments that you make to the clock in addi-
  1247.  
  1248.  
  1249.                                           16
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.  
  1262.           CLOCK Version 3.44                                  March 9, 1993
  1263.  
  1264.  
  1265.                          tion to the automatic adjustments.  The ±sss.cc is
  1266.                          the  amount of  manual  adjustment that  you  have
  1267.                          made.  This may be adjustments made by setting the
  1268.                          clock with the  DOS DATE and TIME commands  or ad-
  1269.                          justments  made by  a time  setting program.   The
  1270.                          YYYY-MM-DD,hh:mm:ss is  the date and time at which
  1271.                          the  adjustment was  made.   It is  very important
  1272.                          that the date  and time be  given with respect  to
  1273.                          the calendar  clock and not the DOS clock, if dif-
  1274.                          ferent.  If  you do not supply the  date and time,
  1275.                          the  current  date and  time will  be used.   This
  1276.                          should be sufficiently  accurate if you just  com-
  1277.                          pleted making the adjustement.
  1278.  
  1279.                          The first M= value that you enter is used only  to
  1280.                          set a base date and time.  Then as you enter addi-
  1281.                          tional values in the  future, CLK will calculate a
  1282.                          new value  for the A= function by adding the aver-
  1283.                          age manual  adjustment per  day to the  current A=
  1284.                          value.  Up to  8 values are  saved in the  CLK.INI
  1285.                          file  (or other file that you  specify).  The more
  1286.                          values you provide and the longer the time period,
  1287.                          the  more accurate  the adjustment  will be.   For
  1288.                          example, if you can  only determine the adjustment
  1289.                          to the  nearest second  (likely), you may  want to
  1290.                          have a week  or more  between manual  adjustments.
  1291.                          The only  restriction is  that the first  and last
  1292.                          manual adjustement must be within one year of each
  1293.                          other.  If  you enter more than 8,  the oldest two
  1294.                          adjustement  values are  collapsed  into a  single
  1295.                          value.
  1296.  
  1297.                          Supplying a new A=  value, presumably based on the
  1298.                          calculations from CLK, deletes  all the M=  values
  1299.                          from the file.  You may either specify a /I option
  1300.                          to specify  the file and read all the functions in
  1301.                          the file, a /M option to specify the file and only
  1302.                          read the  M= functions, or CLK  will automatically
  1303.                          specify the  /M option for  you (but it  will only
  1304.                          know to look for CLK.INI in the directory contain-
  1305.                          ing CLK.EXE).   You may also edit the M= functions
  1306.                          in the file and use  the /M option to force  a re-
  1307.                          calculation.
  1308.  
  1309.                          When  CLK calculates  a new  adjustment value,  it
  1310.                          tries to determine if any of the M= values are out
  1311.                          of line  with the  rest of  the values.   It  will
  1312.                          ignore, but  provide an  error message, if  any of
  1313.  
  1314.  
  1315.                                           17
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.           CLOCK Version 3.44                                  March 9, 1993
  1329.  
  1330.  
  1331.                          the values are  too far away from all  of the oth-
  1332.                          ers.  CLK calculates an average and standard devi-
  1333.                          ation and  ignores all  values (of  adjustment per
  1334.                          day) that are more than 2 standard deviations from
  1335.                          the average.
  1336.  
  1337.                     R=A
  1338.                          The R= function sets restrictions on time changes.
  1339.                          R=A inhibits  All time changes.  When this mode is
  1340.                          set, all  attempts to change the  time are ignored
  1341.                          by  CLOCK.SYS.  This includes time changes attemp-
  1342.                          ted by CLK including time adjustments.  See R=N.
  1343.  
  1344.                     R=B-hh:mm:ss
  1345.                          This function limits the amount of Backward change
  1346.                          of the time.   Any change of more  than the speci-
  1347.                          fied time is ignored.  The "-" is optional as  are
  1348.                          the offset fields.
  1349.                               clk r=b
  1350.                          inhibits all backward changes.
  1351.                               CLK R=B::2
  1352.                          only  allows backward  changes of  two seconds  or
  1353.                          less This might permit CLK to perform  adjustments
  1354.                          but effectively stop other backward changes.
  1355.  
  1356.                     R=F+hh:mm:ss
  1357.                          This function  limits the amount of Forward change
  1358.                          of the time.   Any change of more  than the speci-
  1359.                          fied time is ignored.  The "+" is optional as  are
  1360.                          the offset fields.
  1361.                               CLK R=F+1:00:02
  1362.                          limits forward  changes to  1 hour and  2 seconds.
  1363.                          The R=B and  R=F limits do not apply  to the auto-
  1364.                          matic  conversions between  standard and  daylight
  1365.                          savings  time as these  don't actually  change the
  1366.                          time.  The R=B and R=F functions are also indepen-
  1367.                          dent of the R=A function.
  1368.  
  1369.                     R=N
  1370.                          This function reverses the R=A function and inhib-
  1371.                          its  No clock changes.   The R=A is independent of
  1372.                          the R=B and R=F.  You can set backward and forward
  1373.                          limits  with R=B and  R=F.  Later  you can inhibit
  1374.                          all changes with R=A.  When you do R=N, the previ-
  1375.                          ously set R=B and R=F limits again have an effect.
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.                                           18
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.           CLOCK Version 3.44                                  March 9, 1993
  1395.  
  1396.  
  1397.                     R=R
  1398.                          This function Resets the limits established by R=B
  1399.                          and R=F.  No limits are in effect  after executing
  1400.                          this function.  It has no effect on the R=A mode.
  1401.  
  1402.                     S=C
  1403.                          Sets  both clocks  to  the current  time from  the
  1404.                          calendar clock.   You  can  use this  even if  the
  1405.                          clocks  are disconnected  to  make the  DOS  clock
  1406.                          equal to the calendar clock.  The time zone offset
  1407.                          is set to  00:00:00 and the time zone  name is set
  1408.                          to UTC to indicate that both clocks are set to the
  1409.                          base time.
  1410.  
  1411.                     S=D
  1412.                          Sets both clocks to the current time  from the DOS
  1413.                          clock.  The value from the DOS clock is written to
  1414.                          the calendar clock.   The time zone offset is  set
  1415.                          to 00:00:00  and the zone  name is not  changed to
  1416.                          indicate that  both clocks  are set to  your local
  1417.                          time.
  1418.  
  1419.                     TZ=...
  1420.                          Sets the DOS clock to the correct local time based
  1421.                          on the value of  the expression following the TZ=.
  1422.                          This  expression  conforms  exactly  to the  POSIX
  1423.                          1003.1 standard  for time zone handling.   CLK as-
  1424.                          sumes that  the calendar clock  currently contains
  1425.                          UTC  (also known  as GMT,  Greenwich, ZULU,  and Z
  1426.                          time).   UTC  ("Universal  Time,  Coordinated"  is
  1427.                          usually spoken as "coordinated universal time") is
  1428.                          the name of  the international standard  time that
  1429.                          is provided by  WWV, WWVH, the Naval  Observatory,
  1430.                          and NIST as well as many other services around the
  1431.                          world.    Most  Unix(r)  systems  also support  TZ
  1432.                          although  many only  partially  support the  POSIX
  1433.                          standard.   See  the  notes later  for a  complete
  1434.                          description of the TZ= function.
  1435.  
  1436.                          You  can  put  the  CLK  TZ=...  command  in  your
  1437.                          AUTOEXEC.BAT file.  You should put it prior to any
  1438.                          other  statements that may  create or update files
  1439.                          or you run the risk  of having confusing times  in
  1440.                          your  file  directory (MAKE  could  get especially
  1441.                          confused.).   If you provide a  TZ= function, your
  1442.  
  1443.                                         ____________________
  1444.  
  1445.           Unix is a registered trademark of Unix Systems Laboratories.
  1446.  
  1447.                                           19
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.           CLOCK Version 3.44                                  March 9, 1993
  1461.  
  1462.  
  1463.                          system  will automatically  adjust to  the correct
  1464.                          time zone every  time you boot.  Note  that no at-
  1465.                          tempt is made to change between daylight and stan-
  1466.                          dard time  except  when  you  execute  CLK  TZ=...
  1467.                          Adjusting on the fly is very dangerous.  Many pro-
  1468.                          grams can produce incorrect  results or even  cor-
  1469.                          rupt  your data if  time takes a  big step forward
  1470.                          and are  even more  likely to do  so if  time runs
  1471.                          backward.  See section  ? for a discussion of  the
  1472.                          TZ= format.
  1473.  
  1474.                     W=-back,+forward
  1475.                          The W= function is  used to establish Warning lim-
  1476.                          its on  the time.   Each time  the W=  function is
  1477.                          processed  (usually from  the  CLK.INI file),  the
  1478.                          current time  and the previous  time are compared.
  1479.                          If the current time  is outside the -back,+forward
  1480.                          range  around the previous time, a warning message
  1481.                          is displayed  requiring you to  press a key.   The
  1482.                          program will  also exit  with an ERRORLEVEL  of 1.
  1483.                          The full form of the W= function is:
  1484.                          W=N-days/hh:mm:ss,+days/hh:mm:ss,
  1485.                               YYYY-MM-DD,hh:mm:ss
  1486.  
  1487.                          The days sub-field is a value from 0 to 250  days.
  1488.                          The  days  sub-field combined  with the  time sub-
  1489.                          fields gives  the maximum interval around the pre-
  1490.                          vious time  within  which the  current  time  must
  1491.                          fall.  The previous date and  time follow the sec-
  1492.                          ond comma.  For example,
  1493.                               clk w=-0/00:00:02,+91
  1494.                          will  establish a  range of  minus two  seconds to
  1495.                          plus 91 days.   The first time you  use this func-
  1496.                          tion nothing will happen  except that CLK will add
  1497.                          the current date and time to the command and store
  1498.                          it  in the CLK.INI file.  The next time you use if
  1499.                          from  the CLK.INI  file  with CLK /I,  the current
  1500.                          date  and time  will be  compared to  the previous
  1501.                          date and time and the range.  If the current  time
  1502.                          is outside  the range, a message  is displayed and
  1503.                          CLK pauses.
  1504.  
  1505.                          The sign characters and  all of the sub-fields are
  1506.                          optional.  Missing sub-fields are treated as zero.
  1507.                          The particular separators are not important except
  1508.                          for the  commas.   Any non-digit character  can be
  1509.                          used for the other separators.   The time and date
  1510.                          fields are  appended to  the function by  CLK when
  1511.  
  1512.  
  1513.                                           20
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.  
  1526.           CLOCK Version 3.44                                  March 9, 1993
  1527.  
  1528.  
  1529.                          the CLK.INI  file is written and  are the previous
  1530.                          time to which the next comparison will be made.  A
  1531.                          typical  function might  be W=,31.   This  command
  1532.                          will display  a warning  whenever  time has  moved
  1533.                          backwards  at all  or has  moved forwards  by more
  1534.                          than 31 days since the last time you used CLK  /I.
  1535.                          If you use CLK /I (see below) in your AUTOEXEC.BAT
  1536.                          file,  this is  very likely  to detect  a miss-set
  1537.                          clock or bad clock battery.  Yet it won't generate
  1538.                          a  message on  every boot.  You will  only get  an
  1539.                          "unnecessary" message  if it has been  more than a
  1540.                          month since you last used the PC.
  1541.  
  1542.                          If the "N" character (or "n")  appears immediately
  1543.                          after the "=", CLK does not pause and wait for you
  1544.                          to press a key after printing the warning message.
  1545.                          The "N" allows you  to use CLK in a .BAT  file and
  1546.                          check for the warning  with the IF ERRORLEVEL com-
  1547.                          mand.
  1548.  
  1549.                     /B
  1550.                          The B option  tells CLK to remain in  command mode
  1551.                          even if no other functions or options are present.
  1552.                          The  /B in  itself performs  no operation,  but it
  1553.                          avoids CLK going into  full-screen mode if all you
  1554.                          want to do is display the current status (e.g., in
  1555.                          a .BAT file).
  1556.  
  1557.                     /I[,C]
  1558.                     or
  1559.                     /Ifile[,C]
  1560.                          The I option  tells CLK to  read the CLK.INI  file
  1561.                          (or "file" if that  is given) for additional func-
  1562.                          tions.  These functions are usually A=, L=, and W=
  1563.                          functions that were previously written to the file
  1564.                          by CLK.   You may add any other  functions (but no
  1565.                          options) to the file and they will be processed as
  1566.                          if you had entered them at the end of the  command
  1567.                          line.   If you don't  specify "file" or  you don't
  1568.                          give a path as  part of "file",  CLK will use  the
  1569.                          directory which  contains CLK.EXE.   Thus the  de-
  1570.                          fault  is to  use  CLK.INI in  the directory  that
  1571.                          contains CLK.EXE.  
  1572.  
  1573.                          If you enter an A=, L=, M=, or  W= function or CLK
  1574.                          finds them in  the file, the file  will be updated
  1575.                          with  the new  values  for the  current time  when
  1576.                          appropriate.   If  an adjustment  is made,  the L=
  1577.  
  1578.  
  1579.                                           21
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.           CLOCK Version 3.44                                  March 9, 1993
  1593.  
  1594.  
  1595.                          function  will reflect  the date  and time  of the
  1596.                          latest adjustment.   CLK  will update or  create a
  1597.                          CLK.INI  file even if you don't  use the /I option
  1598.                          if you use  the A=, L=, M=, or W= functions on the
  1599.                          command line.
  1600.  
  1601.                          It is very useful to store your  standard TZ=, C=,
  1602.                          and R=  functions in the CLK.INI file.   Then your
  1603.                          AUTOEXEC.BAT  file can  simply  contain a  CLK  /I
  1604.                          command  to set  your clocks  into their  standard
  1605.                          modes, adjust  the time,  and check for  bad clock
  1606.                          values.  You  can also  reestablish your  standard
  1607.                          modes after  changes with the same command entered
  1608.                          from the DOS prompt or a .BAT file.
  1609.  
  1610.                          The file may be hidden and still  be updated with-
  1611.                          out error.   However, to update  a read-only file,
  1612.                          you must  add ,C to  the end of the  option.  This
  1613.                          indicates that CLK  may Change  the attributes  of
  1614.                          the file in order to update it.  CLK will  restore
  1615.                          the original attributes.   System files may not be
  1616.                          updated.
  1617.  
  1618.                     /M[,C]
  1619.                     or
  1620.                     /Mfile[,C]
  1621.                          The M option is  identical to the I option  except
  1622.                          that only the M= function  lines are read from the
  1623.                          file.  Its  primary use  is internal  to CLK  when
  1624.                          processing an  M= function from  the command line.
  1625.                          You may also use /Mfile to specify the location of
  1626.                          the file when  entering M= values.   You may  also
  1627.                          use  the M  option to  cause recalculation  of the
  1628.                          adjustment factor at any time (e.g., after editing
  1629.                          the file).
  1630.  
  1631.                     /P
  1632.                     or
  1633.                     /PN
  1634.                          Controls the use  of password  protection of  mode
  1635.                          changes.  When you use /P, CLK will ask you for  a
  1636.                          new password.  It will then ask you to repeat  the
  1637.                          password to ensure that you entered what you want.
  1638.                          It does not display the password as you enter  it.
  1639.                          The password is then passed to CLOCK.SYS and pass-
  1640.                          word protection  is enabled.   On future  calls to
  1641.                          CLOCK.SYS, you  will be asked for  the password if
  1642.                          protection is enabled.  You may use /PN to disable
  1643.  
  1644.  
  1645.                                           22
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.  
  1656.  
  1657.  
  1658.           CLOCK Version 3.44                                  March 9, 1993
  1659.  
  1660.  
  1661.                          password protection, but you  will have to provide
  1662.                          the current password  to do so.  If  used with the
  1663.                          /S feature, the password protection will remain in
  1664.                          effect even across reboots.  /P should be the last
  1665.                          field on a CLK command line.
  1666.  
  1667.                     /S
  1668.                     or
  1669.                     /Sfile
  1670.                          Saves the current copy  of CLOCK.SYS as it resides
  1671.                          in memory.  If  you do not  specify the file,  the
  1672.                          memory version is written to file CLOCK.NEW in the
  1673.                          same directory that contains  CLK.EXE.  While  you
  1674.                          may  directly  overwrite the  file  CLOCK.SYS, you
  1675.                          should be  very careful doing so  as whatever your
  1676.                          current  state is  will  take effect  on the  next
  1677.                          boot.
  1678.  
  1679.                          PLEASE  MAKE  A  BACKUP  COPY   of  your  original
  1680.                          CLOCK.SYS before replacing it  with a saved  file.
  1681.                          The saved  file does not  do any  probing at  boot
  1682.                          time as  it already knows exactly  what your clock
  1683.                          is.  It does  not need any  parameters on the  de-
  1684.                          vice= line in CONFIG.SYS.
  1685.  
  1686.                          The /S  option may be extremely  useful for anyone
  1687.                          with multiple  similar systems  to maintain.   You
  1688.                          can set  up all  of your options  once on  one ma-
  1689.                          chine, save those with the /S option, and then use
  1690.                          the  saved file  to  directly install  on all  the
  1691.                          other machines.   If you use  password protection,
  1692.                          no  one can  change  the other  systems except  by
  1693.                          modifying CONFIG.SYS  to  remove  the  loading  of
  1694.                          CLOCK.SYS.
  1695.  
  1696.                          You will still need  to run CLK  as part of  every
  1697.                          boot operation  (e.g., in AUTOEXEC.BAT)  to do any
  1698.                          automatic adjustment (A= and  L= functions), check
  1699.                          for clock failures (W= function), and check to see
  1700.                          whether the clock should  use the standard or day-
  1701.                          light offsets (TZ= function).  These functions are
  1702.                          not processed  automatically by  CLOCK.SYS because
  1703.                          they would increase the  size of the device driver
  1704.                          to an unacceptable limit.
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.                                           23
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.  
  1724.           CLOCK Version 3.44                                  March 9, 1993
  1725.  
  1726.  
  1727.                     /?
  1728.                          "/?" or any  error will cause  CLK to display  the
  1729.                          usage format.  If you have an error in any  field,
  1730.                          CLK first displays that field.
  1731.  
  1732.                     TZ=:?
  1733.                          "TZ=:?" or any error in a TZ= function that refers
  1734.                          to a  pre-defined time zone causes  CLK to display
  1735.                          all the  current pre-defined time  zone names  and
  1736.                          their associated values.
  1737.  
  1738.  
  1739.           2.2  Format of TZ= Function
  1740.  
  1741.           The format of TZ=... can get quite complicated as the standard is
  1742.           trying to  deal with  all time  zones and  daylight savings  time
  1743.           rules around the world.  The full format is:
  1744.  
  1745.                TZ=:zone
  1746.                or
  1747.                TZ=STD[offset][DAY[offset][,start[/time],end[/time]]]
  1748.  
  1749.           Parameters     zone
  1750.                          The form TZ=:zone  is the one you  are most likely
  1751.                          to need.  CLK knows the offsets  and daylight sav-
  1752.                          ings time rules  for most of the U.S.  and all you
  1753.                          have to supply is the name of your time zone.  The
  1754.                          time zones currently known to CLK are:
  1755.                          EST  Eastern U.S. with automatic daylight
  1756.                          CST  Central U.S. with automatic daylight
  1757.                          MST  Mountain U.S. with automatic daylight
  1758.                          PST  Pacific U.S. with automatic daylight
  1759.                          HST  Hawaiian with no daylight savings time
  1760.  
  1761.                          You can use CLK TZ=:? to display the list of  pre-
  1762.                          defined zone names and their values.
  1763.  
  1764.                          If you would like your favorite time added, please
  1765.                          send  me the names, offset from  UTC, and any day-
  1766.                          light savings time  rules that are different  from
  1767.                          the U.S.  NOTE:  The names can be composed of  any
  1768.                          characters except digits, plus, minus, and  comma.
  1769.                          They can  be up  to 32 characters  long.   Case is
  1770.                          preserved in  the names only for  later display by
  1771.                          CLK.  You can call your zone MyZone.
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.                                           24
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.           CLOCK Version 3.44                                  March 9, 1993
  1791.  
  1792.  
  1793.                          Case is not important  in matching the zone names.
  1794.                          tz=:cst is  the equivalent of TZ=:CST.   Both will
  1795.                          find the definition of CST.
  1796.                                   
  1797.                     You don't have to wait for me to modify CLK in order to
  1798.                     use your local rules or just try something out.  That's
  1799.                     what the long form is for.
  1800.  
  1801.                     STD
  1802.                          is any time  zone name for standard  time that you
  1803.                          want to use.  See the note above for the rules.
  1804.  
  1805.  
  1806.                     offset
  1807.                          is the difference between  your local time and UTC
  1808.                          and is expressed as hh[:mm[:ss]] with an  optional
  1809.                          leading + or -.  Offsets for times West of  Green-
  1810.                          wich are  positive and those East are negative.  A
  1811.                          24-hour  clock  is used  with  times  running from
  1812.                          00:00:00  to  23:59:59.    Mountain Standard  time
  1813.                          would be expressed as:
  1814.                               TZ=MST+07:00:00
  1815.                                    or
  1816.                               TZ=MST7
  1817.                          and that's what you would use if you live in  Ari-
  1818.                          zona  and  don't want  any  daylight  savings time
  1819.                          adjustments.
  1820.  
  1821.                     DAY
  1822.                          is the  time zone name for  daylight savings time.
  1823.                          If  you don't  use daylight  savings time  in your
  1824.                          location, you should not supply this or any of the
  1825.                          following fields.
  1826.  
  1827.                          The offset  for daylight time is in  the same form
  1828.                          as for  standard time.   If  you  don't give  this
  1829.                          offset, it  is assumed to  be one hour  later than
  1830.                          standard time.  Thus a more complete specification
  1831.                          of the Eastern time zone would be:
  1832.                               TZ=EST+05:00:00EDT+04:00:00
  1833.                                    or
  1834.                               TZ=EST5EDT4
  1835.                                    or
  1836.                               TZ=EST5EDT     (since  daylight  is one  hour
  1837.                                              later by default)
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.                                           25
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.  
  1856.           CLOCK Version 3.44                                  March 9, 1993
  1857.  
  1858.  
  1859.                     start
  1860.                          is the day of  the year on which  daylight savings
  1861.                          time starts.  There are three formats that you can
  1862.                          use to give this day.  They are given below.
  1863.  
  1864.                     end
  1865.                          is the  day  of the  year on  which standard  time
  1866.                          starts  again.   Note that  in the  Southern hemi-
  1867.                          sphere it is quite possible for "end" to be earli-
  1868.                          er in  the year  than "start" as  daylight savings
  1869.                          time will include December and January.  end is in
  1870.                          the same  format as start.   Note from  the syntax
  1871.                          above  that you  must provide  end if  you provide
  1872.                          start.
  1873.  
  1874.                     time
  1875.                          is the time  of day that  the change takes  place.
  1876.                          It is  in exactly the same format as offset except
  1877.                          that leading + and  - signs are  not allowed.   If
  1878.                          you do not specify  the time, 02:00:00 is  used as
  1879.                          the default.
  1880.  
  1881.           The day of the year form for start and end may be any of:
  1882.  
  1883.                     Jn
  1884.                          where n is a Julian day of the year from 1 to 365.
  1885.                          This form  does not allow you to refer to February
  1886.                          29.  Day  59 is always February  28 and Day 60  is
  1887.                          always March 1.  This is  most useful in locations
  1888.                          where  a particular  calendar  date is  used every
  1889.                          year.
  1890.  
  1891.                     n
  1892.                          where n is a Julian day of the year from 0 to 365.
  1893.                          This form does allow you to refer to February  29.
  1894.                          January 1  is day  0, February 28  is day  58, and
  1895.                          either February 29 or March  1 is day 59 depending
  1896.                          on whether it is a leap year or not.  Not the most
  1897.                          useful of  forms but  it does deal  with locations
  1898.                          that might  specify February  29 as the  date that
  1899.                          time changes.
  1900.  
  1901.                     Mm.w.d
  1902.                          is used in places like the U.S. that do not speci-
  1903.                          fy  a date, but  rather specify a rule.   m is the
  1904.                          month  (1  to 12).    d is  the  day  of the  week
  1905.                          (0=Sunday, 1=Monday, ...  6=Saturday).   w is  the
  1906.                          week of the  month (1 to 5).  Week 1 indicates the
  1907.  
  1908.  
  1909.                                           26
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.  
  1920.  
  1921.  
  1922.           CLOCK Version 3.44                                  March 9, 1993
  1923.  
  1924.  
  1925.                          first time that day d occurs in that month.   Week
  1926.                          5 indicates the  last time  that day  d occurs  in
  1927.                          that  month whether  it  is the  4th or  5th time.
  1928.                          Thus the U.S. rule is
  1929.                               M4.1.0/02:00:00,M10.5.0/02:00:00
  1930.                          or the first Sunday in April at 2AM until the last
  1931.                          Sunday in October at 2AM.
  1932.  
  1933.           The long form for Central U.S. time is:
  1934.  
  1935.                TZ=CST+06:00:00CDT+05:00:00,M4.1.0/02:00:00,M10.5.0/02:00:00
  1936.                          or
  1937.                TZ=CST6CDT5,M4.1.0/2,M10.5.0/2     (just leaving out zeros)
  1938.                          or
  1939.                TZ=CST6CDT,M4.1.0,M10.5.0          (since 2AM is default)
  1940.                          or
  1941.                TZ=CST6CDT                         (since  the U.S.  rule is
  1942.                                                   the default)
  1943.  
  1944.  
  1945.           2.3  Using CLK
  1946.  
  1947.           The most common  use of CLK will be to handle  your time zone and
  1948.           daylight savings time changes.  You need only do the following:
  1949.  
  1950.           1.   Set your clocks to UTC.
  1951.  
  1952.           2.   Include the following line in your AUTOEXEC.BAT file.
  1953.                     CLK TZ=:zone   (where you  use one  of the  pre-defined
  1954.                                    zones)
  1955.                          or
  1956.                     CLK TZ=...     (where you define your own rules)
  1957.  
  1958.           That's it.  Everything else will take care of itself.  
  1959.  
  1960.           The only other time you will need to do anything is if you decide
  1961.           to correct your calendar clock to a more accurate time.  You will
  1962.           probably use TIMESET  or one of the other programs  that call the
  1963.           Naval Observatory or NIST or maybe just  your watch that you have
  1964.           set accurately.
  1965.  
  1966.           If you don't want to have to change the configuration of the time
  1967.           setting program,  you may want  to have it  always set UTC  or at
  1968.           least your local standard  time.  If you want to have  it set UTC
  1969.           time, do the following:
  1970.  
  1971.                CLK S=C C=W
  1972.                run your time set program
  1973.  
  1974.  
  1975.                                           27
  1976.  
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.  
  1986.  
  1987.  
  1988.           CLOCK Version 3.44                                  March 9, 1993
  1989.  
  1990.  
  1991.                CLK TZ=...     (your normal TZ value)
  1992.  
  1993.           The  C=W in the first  line is only required  if you normally run
  1994.           with the clocks disconnected.
  1995.  
  1996.           Note that if you tell the time set program what your current time
  1997.           zone is, you don't have to do anything unless you have the clocks
  1998.           disconnected.
  1999.  
  2000.           Notes     Leaving your clock on local time                    ________________________________
  2001.                     If you  don't want  to be bothered  with UTC,  CLK will
  2002.                     quite happily work with your calendar clock set  to its
  2003.                     current  value.   For  example, let's  assume that  you
  2004.                     currently have both clocks set to Pacific Standard Time
  2005.                     and you  don't really want  to be bothered  changing to
  2006.                     UTC, but you would like future changes between standard
  2007.                     and daylight  time to  be handled automatically.   Just
  2008.                     use the following statement in AUTOEXEC.BAT:
  2009.                          CLK TZ=PST0PDT
  2010.  
  2011.                     CLK believes whatever you tell it and will quite happi-
  2012.                     ly operate  assuming that  PST is  equal to  UTC.   You
  2013.                     could  even use  CLK with  your calendar  clock  set to
  2014.                     Pacific Daylight Time by using:
  2015.                          CLK TZ=PST1PDT
  2016.  
  2017.                     Avoiding missed days when your PC stays on all night,
  2018.                     and missed years and leap days on type 4 and 6 clocks                    _____________________________________________________
  2019.                     If your PC is often left on over midnight  and seems to
  2020.                     miss the change to a new day, use:
  2021.                          CLK C=R TZ=...
  2022.                     in your AUTOEXEC.BAT file to have CLOCK.SYS periodical-
  2023.                     ly read the time and date  from the calendar clock.  If
  2024.                     your clock is a type  4 or 6 clock that doesn't  update
  2025.                     years automatically and doesn't handle leap  days, then
  2026.                     this setting  also ensures that leaving your PC on over
  2027.                     the end of  a year or across February  29 doesn't cause
  2028.                     you to get the wrong date.
  2029.  
  2030.                     Using CLK.INI to simplify your commands                    _______________________________________
  2031.                     If you always  use the same functions, you  may want to
  2032.                     edit the CLK.INI file that is included in this release.
  2033.                     You can include  your TZ=, C=, and R=  functions in the
  2034.                     file and just use:
  2035.                          CLK /I
  2036.                     in your AUTOEXEC.BAT file.
  2037.  
  2038.                     Adding and subtracting time                    ___________________________
  2039.  
  2040.  
  2041.                                           28
  2042.  
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.  
  2054.           CLOCK Version 3.44                                  March 9, 1993
  2055.  
  2056.  
  2057.                     You can pretty much do anything including simple arith-
  2058.                     metic  on  your clocks  by using  the functions  in the
  2059.                     correct sequence.  Let's  say that you  want to add  12
  2060.                     hours  to the current  time in both  clocks because you
  2061.                     inadvertently  set AM  time instead  of PM  time.   The
  2062.                     following function sequence will do that:
  2063.                          CLK TZ=Igoofed-12 S=D TZ=:pst
  2064.  
  2065.                     The TZ=Igoofed-12  (or use any other name for the zone)
  2066.                     sets your DOS clock to 12 hours later than the calendar
  2067.                     clock.  (Yes, I know that time zone offsets seem  back-
  2068.                     wards  since you subtract them from  the base time, but
  2069.                     that's the way the official standards have them.)
  2070.  
  2071.                     The S=D sets  both clocks to the value in the DOS clock
  2072.                     with a zero offset.
  2073.  
  2074.                     The TZ=:pst should be  replaced by whatever your normal
  2075.                     TZ function is  or even by a /I to  pull in your normal
  2076.                     settings.
  2077.  
  2078.                     If you normally have your clocks disconnected, insert a
  2079.                     C=W function as the first function.
  2080.  
  2081.                     Correcting inadvertent problems                    _______________________________
  2082.                     Just remember that except for the S=D function, CLK and
  2083.                     CLOCK.SYS  always start  with the  assumption  that the
  2084.                     calendar clock  is the base  and do all  their calcula-
  2085.                     tions  from that point.  Thus  you can play with TZ and
  2086.                     other functions as much as you want and always get back
  2087.                     to your normal local time just by using your normal  TZ
  2088.                     command.  The calendar clock will not have been affect-
  2089.                     ed unless you did  something to set  the time or  date.
  2090.                     You can  avoid even that problem  by disconnecting your
  2091.                     clocks  (C=D) or  restricting time  changes (R=A).   In
  2092.                     fact, if  you have trouble with some program messing up
  2093.                     your clocks, try the following:
  2094.  
  2095.                          CLK C=D
  2096.                          execute program
  2097.                          CLK S=C C=W (or C=R) TZ=...  (your normal)
  2098.  
  2099.                     If you  have your  standard C= and  TZ= functions  in a
  2100.                     file, you can simplify this as:
  2101.  
  2102.                          CLK C=D
  2103.                          execute program
  2104.                          CLK S=C /I
  2105.  
  2106.  
  2107.                                           29
  2108.  
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.  
  2118.  
  2119.  
  2120.           CLOCK Version 3.44                                  March 9, 1993
  2121.  
  2122.  
  2123.                     You may  even want  to make  up batch  files containing
  2124.                     this sequence to run  those troublesome programs.  Some
  2125.                     games are major causes of problems because they set the
  2126.                     DOS  clock  running faster  or  slower  than normal  to
  2127.                     control the pace of the game.   As long as they restore
  2128.                     the normal rate when they exit, the above sequence will
  2129.                     eliminate any clock drift problems.
  2130.  
  2131.                     Fast DOS clock drift                    ____________________
  2132.                     Some high-speed communication  programs will also cause
  2133.                     the DOS clock  to run slow by causing the  BIOS to miss
  2134.                     clock interrupts.   Fortunately, a C=R function  should
  2135.                     virtually eliminate problems of this type.
  2136.  
  2137.  
  2138.           2.4  Examples
  2139.  
  2140.                clk A=0.34
  2141.                     sets an adjustment factor of 0.34 seconds per day.  The
  2142.                     A=0.34  function will  be written  to the  CLK.INI file
  2143.                     along with an  L= function with the current  time and a
  2144.                     zero remaining adjustment.  Every time thereafter, that
  2145.                     CLK  is run with the /I option, it will check to see if
  2146.                     it is  time to  adjust the clocks.   About  every third
  2147.                     day, it will add 1 second to both clocks.
  2148.  
  2149.                clk s=c /i
  2150.                     sets the DOS  clock to the current  calendar clock time
  2151.                     without any time  zone adjustment.   The /i causes  all
  2152.                     functions in the  CLK.INI file to be added.   If one of
  2153.                     them is a tz function, we have corrected the DOS  clock
  2154.                     for any changes  made to it and re-established our time
  2155.                     zone.  This is a good command line to use following a 
  2156.                          clk c=d
  2157.                     and other operations that may have led to an  incorrect
  2158.                     time in the DOS clock.
  2159.  
  2160.                clk c=r tz=:est r=b-00:00:02 r=f+00:00:02
  2161.                     sets CLOCK.SYS  to read the calendar  clock about every
  2162.                     10 seconds  and re-synchronize  the DOS clock  with it;
  2163.                     applies the  appropriate Eastern time zone (standard or
  2164.                     daylight  depending on date);  and prohibits changes to
  2165.                     the clock of more than 2 seconds in either direction.
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.                                           30
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.  
  2184.  
  2185.  
  2186.           CLOCK Version 3.44                                  March 9, 1993
  2187.  
  2188.  
  2189.           2.5  Errors
  2190.  
  2191.           When errors are detected, CLK prints a message.  It also sets the
  2192.           ERRORLEVEL on each program termination as follows:
  2193.  
  2194.           0    Normal termination or only warning messages.
  2195.  
  2196.           1    Time outside warning range.  Warning issued.
  2197.  
  2198.           2    Error in command line or CLK.INI file functions.  The  func-
  2199.                tion with the error is displayed followed by the appropriate
  2200.                usage rules.
  2201.  
  2202.           3    Internal error or  system error (e.g., unable to open handle
  2203.                to CLOCK.SYS).
  2204.  
  2205.  
  2206.           2.6  Future Enhancements
  2207.  
  2208.           Several enhancements are planned for future releases of CLK.
  2209.  
  2210.                -    Full screen interface that  displays the current status
  2211.                     of all the things that CLK and CLOCK.SYS know and  lets
  2212.                     you change them just by editing the screen.  The rather
  2213.                     clunky command  line interface  needs to remain  as its
  2214.                     compact  function definitions  are what  you want  in a
  2215.                     .BAT file.
  2216.  
  2217.                -    Direct dialing of the Naval Observatory  or NIST to get
  2218.                     the correct  time with  automatic creation of  M= func-
  2219.                     tions from the results.
  2220.  
  2221.  
  2222.  
  2223.  
  2224.  
  2225.  
  2226.  
  2227.  
  2228.  
  2229.  
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.                                           31
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.  
  2249.  
  2250.  
  2251.  
  2252.           CLOCK Version 3.44                                  March 9, 1993
  2253.  
  2254.  
  2255.           3  CLKDEMO.EXE
  2256.  
  2257.           A simple version of the CLK program, called CLKDEMO, is  provided
  2258.           in both executable  and source code form.   CLKDEMO only provides
  2259.           support for the C= functions and displaying the clock status.  It
  2260.           is included  to show you  how to add  clock handling to  your own
  2261.           applications.   CLKDEMO  is written  in  C and  is compiled  with
  2262.           Microsoft C 5.1.
  2263.  
  2264.  
  2265.           3.1  CLKDEMO Command Line
  2266.  
  2267.           Syntax    CLKDEMO [C=A|D|R|W] [/?]
  2268.  
  2269.           The functions provided work exactly as  they do in CLK.   CLKDEMO
  2270.           also displays the status and the current times.
  2271.  
  2272.           Since CLKDEMO.EXE is merely a subset of CLK.EXE, it isn't  terri-
  2273.           bly useful as a utility in its own  right.  Its value is that the
  2274.           source  code is  provided.   There  are three  source code  files
  2275.           provided.   CLKDEMO.C is the  main program  and performs  command
  2276.           interpretation and execution.  IOCTL.C is a set of functions that
  2277.           read  and write  the CLOCK$  device  driver using  the DOS  IOCTL
  2278.           functions.  IOCTL.H  is a set  of definitions which  are used  by
  2279.           CLKDEMO and  IOCTL.C.   CLKTYP.H is  a  list of  the clock  types
  2280.           currently supported by these programs.  It is used to display the
  2281.           type.
  2282.  
  2283.  
  2284.  
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.                                           32
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.  
  2315.  
  2316.  
  2317.  
  2318.           CLOCK Version 3.44                                  March 9, 1993
  2319.  
  2320.  
  2321.           4  IOCTL - API TO CLOCK.SYS
  2322.  
  2323.           IOCTL  is provided to allow you to build your own applications to
  2324.           use  the additional functions that CLOCK.SYS provides.  There are
  2325.           several  APIs  (Application Programming  Interfaces)  provided as
  2326.           part of IOCTL.  These  APIs  are sufficient to perform all of the
  2327.           extended functions.
  2328.  
  2329.           All of  the APIs  are defined  to be directly  callable from  all
  2330.           Microsoft compatible  languages including MASM,  FORTRAN, Pascal,
  2331.           and  BASIC.  Languages  other than  C refer to  the API  names as
  2332.           upper case characters.  Object code versions are provided for the
  2333.           small, medium,  and large  memory models.   These  may be  linked
  2334.           directly with your  applications.  The  object code versions  are
  2335.           SIOCTL.OBJ, MIOCTL.OBJ, and LIOCTL.OBJ for the small, medium, and
  2336.           large models respectively.
  2337.  
  2338.  
  2339.           4.1  Data Structures
  2340.  
  2341.           Data structures are defined in ioctl.h that are used in the calls
  2342.           to the IOCTL functions.
  2343.  
  2344.  
  2345.           /* "modes" holds flags that control the operation of CLOCK.SYS */
  2346.  
  2347.           struct modes {
  2348.               unsigned : 9;
  2349.               unsigned day_light: 1;
  2350.               unsigned disp_24 : 1;
  2351.               unsigned disp_tim : 1;
  2352.               unsigned pw_ena : 1;
  2353.               unsigned disabl : 1;
  2354.               unsigned chk_forw : 1;
  2355.               unsigned chk_back : 1;
  2356.           };
  2357.  
  2358.           /* "off" holds a time offset in hours, minutes, and seconds. */
  2359.  
  2360.           struct off {
  2361.               int hour;
  2362.               int minute;
  2363.               int second;
  2364.           };
  2365.  
  2366.  
  2367.  
  2368.  
  2369.  
  2370.  
  2371.                                           33
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.  
  2381.  
  2382.  
  2383.  
  2384.           CLOCK Version 3.44                                  March 9, 1993
  2385.  
  2386.  
  2387.           /* "date_time" is a structure that holds a date and time.    */
  2388.  
  2389.           struct date_time {
  2390.               int year;
  2391.               int month;
  2392.               int day;
  2393.               struct off time;
  2394.               int hsecond;
  2395.           };
  2396.  
  2397.           /* "time_zone" holds a time zone name and offset.   */
  2398.  
  2399.           struct time_zone {
  2400.               struct off offs;
  2401.               unsigned char zone[32];
  2402.           };
  2403.  
  2404.           /* "limit"  is used to  hold the data  that sets time  limits for
  2405.           changes.    */
  2406.  
  2407.           struct limit {
  2408.               struct off back;
  2409.               struct off forward;
  2410.           };
  2411.           /*  "disp" is used to  hold the data  that specifies the location
  2412.           and attributes of the continuous time display.   */
  2413.  
  2414.           struct disp {
  2415.               int x;
  2416.               int y;
  2417.               int attribute;
  2418.           };
  2419.  
  2420.  
  2421.  
  2422.  
  2423.  
  2424.  
  2425.  
  2426.  
  2427.  
  2428.  
  2429.  
  2430.  
  2431.  
  2432.  
  2433.  
  2434.  
  2435.  
  2436.  
  2437.                                           34
  2438.  
  2439.  
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.  
  2450.           CLOCK Version 3.44                                  March 9, 1993
  2451.  
  2452.  
  2453.           /* CLOCK_DATA is the  CLOCK.SYS data that  is returned by  clksta
  2454.           (AKA CLKSTA for FORTRAN,  Pascal, and BASIC languages).   Because
  2455.           we  need to  be language  independent, all of  the data  is word-
  2456.           aligned.  Only  the data types int and character  are used.  Some
  2457.           of the int data is encoded bits or addresses.  */
  2458.  
  2459.           struct CLOCK_DATA {
  2460.               int connected;               /* Connection state          */
  2461.               struct modes mode;           /* Mode bits                 */
  2462.               struct date_time cal_time;   /* Current date and time     */
  2463.               struct time_zone standard;   /* Offset of standard UTC    */
  2464.               struct time_zone daylight;   /* Daylight offset           */
  2465.               struct limit rules;          /* Maximum clock movement    */
  2466.               struct disp display;         /* Time display loc and attr */
  2467.               unsigned char vers[6];       /* CLOCK.SYS version nnn.nn  */
  2468.               int clock_type;              /* Type of clock installed   */
  2469.               int ct_1;                    /* Data for clock type       */
  2470.               int ct_2;
  2471.               int ct_3;
  2472.               int ct_4;
  2473.               unsigned int clock_seg;      /* Segment CLOCK.SYS loaded at*/
  2474.               unsigned int clock_long;     /* Size of CLOCK.SYS          */
  2475.           };
  2476.  
  2477.           This data structure is treated as the following integer array  in
  2478.           the FORTRAN and BASIC languages.
  2479.  
  2480.           BASIC          _____
  2481.                OPTION BASE 1
  2482.                DIM CDATA(66)
  2483.  
  2484.           FORTRAN          _______
  2485.                INTEGER*2 CDATA(66)
  2486.  
  2487.           ARRAY INDEX         CONTENTS                 STRUCTURE ELEMENT          ___________         ________                 _________________
  2488.  
  2489.           CDATA(1)       =    Connection state         connected
  2490.           CDATA(2)       =    Mode bits                mode
  2491.           CDATA(3)       =    Year from calendar clock cal_time.year
  2492.           CDATA(4)       =    Month                    cal_time.month
  2493.           CDATA(5)       =    Day                      cal_time.day
  2494.           CDATA(6)       =    Hour                     cal_time.offs.hour
  2495.           CDATA(7)       =    Minute                   cal_time.offs.minute
  2496.           CDATA(8)       =    Second                   cal_time.offs.second
  2497.           CDATA(9)       =    100th of second          cal_time.hsecond
  2498.           CDATA(10)      =    Standard hours from UTC  standard.offs.hour
  2499.           CDATA(11)      =    Standard minutes         standard.offs.minute
  2500.           CDATA(12)      =    Standard seconds         standard.offs.second
  2501.  
  2502.  
  2503.                                           35
  2504.  
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.  
  2513.  
  2514.  
  2515.  
  2516.           CLOCK Version 3.44                                  March 9, 1993
  2517.  
  2518.  
  2519.           CDATA(13) -                                  standard.zone
  2520.           CDATA(28)      =    Standard time zone LJSF
  2521.           CDATA(29)      =    Daylight hours from UTC  daylight.offs.hour
  2522.           CDATA(30)      =    Daylight minutes         daylight.offs.minute
  2523.           CDATA(31)      =    Daylight seconds         daylight.offs.second
  2524.           CDATA(32) -                                  daylight.zone
  2525.           CDATA(47)      =    Daylight time zone LJSF
  2526.           CDATA(48)      =    Maximum hours backward   rules.back.hour
  2527.           CDATA(49)      =    Maximum minutes backward rules.back.minute
  2528.           CDATA(50)      =    Maximum seconds backward rules.back.second
  2529.           CDATA(51)      =    Maximum hours forward    rules.forward.hour
  2530.           CDATA(52)      =    Maximum minutes forward  rules.forward.minute
  2531.           CDATA(53)      =    Maximum seconds forward  rules.forward.second
  2532.           CDATA(54)      =    x cursor position        display.x
  2533.           CDATA(55)      =    y cursor position        display.y
  2534.           CDATA(56)      =    attribute                display.attribute
  2535.           CDATA(57) -                                  vers
  2536.           CDATA(59)      =    CLOCK.SYS version LJSF
  2537.           CDATA(60)      =    Clock type               clock_type
  2538.           CDATA(61)      =    I/O address, base memory ct_1
  2539.                               segment, or base year
  2540.           CDATA(62)      =    Read memory offset       ct_2
  2541.           CDATA(63)      =    Write-0 memory offset    ct_3
  2542.           CDATA(64)      =    Write-1 memory offset    ct_4
  2543.           CDATA(65)      =    Segment address          clock_seg
  2544.                               where CLOCK.SYS is loaded
  2545.           CDATA(66)      =    Length of CLOCK.SYS      clock_long
  2546.  
  2547.  
  2548.           4.2  clksta
  2549.  
  2550.           ■  Summary
  2551.  
  2552.           C          _
  2553.  
  2554.           #include <ioctl.h>
  2555.  
  2556.           extern int pascal far clksta(struct CLOCK_DATA *cdata);
  2557.  
  2558.           BASIC          _____
  2559.  
  2560.           OPTION BASE 1
  2561.           DIM CDATA(66)
  2562.  
  2563.           DECLARE FUNCTION CLKSTA%(BYVAL Addr AS INTEGER)
  2564.  
  2565.           STATUS% = CLKSTA(VARPTR(CDATA(1)))
  2566.  
  2567.  
  2568.  
  2569.                                           36
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.  
  2579.  
  2580.  
  2581.  
  2582.           CLOCK Version 3.44                                  March 9, 1993
  2583.  
  2584.  
  2585.           FORTRAN          _______
  2586.  
  2587.           INTEGER*2 CDATA(66)
  2588.           INTEGER*2 STATUS
  2589.           INTEGER*2 CLKSTA
  2590.  
  2591.           STATUS = CLKSTA(CDATA)
  2592.  
  2593.           ■  Description
  2594.  
  2595.           clksta  returns  all  of the  information  about  CLOCK.SYS in  a
  2596.           structure.  In FORTRAN and  BASIC the structure appears to be  an
  2597.           integer  array.  The above structure declarations can be approxi-
  2598.           mated  in Pascal.  For  a description of the  values of each ele-
  2599.           ment, see the individual APIs below.  The elements not  described
  2600.           as part of the input to other functions are:
  2601.  
  2602.           unsigned char vers[6];      /* CLOCK.SYS version nnn.nn     */
  2603.           int clock_type;             /* Type of clock installed      */
  2604.           int ct_1;                   /* Data for clock type          */
  2605.           int ct_2;
  2606.           int ct_3;
  2607.           int ct_4;
  2608.           unsigned int clock_seg;     /* Segment CLOCK.SYS loaded at  */
  2609.           unsigned int clock_long;    /* Size of CLOCK.SYS            */
  2610.  
  2611.           CDATA(57) -
  2612.           CDATA(59)      =    CLOCK.SYS version LJSF characters
  2613.           CDATA(60)      =    Clock type (see type numbers in appendix B)
  2614.           CDATA(61)      =    I/O  address, base  memory  segment, or  base
  2615.                               year
  2616.           CDATA(62)      =    Read memory offset
  2617.           CDATA(63)      =    Write-0 memory offset
  2618.           CDATA(64)      =    Write-1 memory offset
  2619.           CDATA(65)      =    Segment address at which CLOCK.SYS is loaded
  2620.           CDATA(66)      =    Length in bytes of CLOCK.SYS
  2621.  
  2622.                vers or CDATA(57) - CDATA(59)
  2623.                     Is  the version  number  of the  CLOCK.SYS that  is in-
  2624.                     stalled.   This  is  returned as  a 6-character,  left-
  2625.                     justified, space-filled (LJSF)  character string.   For
  2626.                     example, "3.49  ".
  2627.  
  2628.                clock_type or CDATA(60)
  2629.                     Is the type number of the clock being used.  See Appen-
  2630.                     dix B for the type numbers.
  2631.  
  2632.  
  2633.  
  2634.  
  2635.                                           37
  2636.  
  2637.  
  2638.  
  2639.  
  2640.  
  2641.  
  2642.  
  2643.  
  2644.  
  2645.  
  2646.  
  2647.  
  2648.           CLOCK Version 3.44                                  March 9, 1993
  2649.  
  2650.  
  2651.                ct_1 or CDATA(61)
  2652.                     Is the value of the first clock parameter.  This is the
  2653.                     base I/O  address for I/O  bus clocks, the  base memory
  2654.                     segment address for  memory-mapped clocks, or  the base
  2655.                     year for the AT&T clocks.
  2656.  
  2657.                ct_2 or CDATA(62)
  2658.                     Is the read offset for memory-mapped clocks.
  2659.  
  2660.                ct_3 or CDATA(63)
  2661.                     Is the write 0-bits offset for memory-mapped clocks.
  2662.  
  2663.                ct_4 or CDATA(64)
  2664.                     Is the write 1-bits offset for memory-mapped clocks.
  2665.  
  2666.                clock_seg or CDATA(65)
  2667.                     Is the  segment address  at which CLOCK.SYS  is loaded.
  2668.                     CLOCK.SYS always starts at offset zero in this segment.
  2669.  
  2670.                clock_long or CDATA(66)
  2671.                     Is the length of CLOCK.SYS in bytes.
  2672.  
  2673.           ■ Arguments         cdata
  2674.                                    is a pointer to  a location to place the
  2675.                                    current    state     information    from
  2676.                                    CLOCK.SYS.
  2677.  
  2678.           ■  Return Value
  2679.  
  2680.           If clksta is  successful, the function returns 0.   Otherwise, it
  2681.           returns a non-zero value and _doserrno is set to the  correspond-
  2682.           ing error code.  Possible values are:
  2683.  
  2684.                0001h     Invalid  function.    This  should  indicate  that
  2685.                          CLOCK.SYS is not installed.  It is the error  that
  2686.                          the DOS clock device  driver would return since it
  2687.                          doesn't handle these functions.
  2688.  
  2689.                0005h     Access denied.  Indicates  that DOS would not open
  2690.                          a handle for read access.  You may not have enough
  2691.                          handles available.
  2692.  
  2693.                0006h     Invalid handle.  Should not happen.
  2694.  
  2695.                000Dh     Invalid data.  CLOCK.SYS reported a bad byte count
  2696.                          or otherwise  did not  process the request.   This
  2697.                          should not happen.
  2698.  
  2699.  
  2700.  
  2701.                                           38
  2702.  
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.  
  2711.  
  2712.  
  2713.  
  2714.           CLOCK Version 3.44                                  March 9, 1993
  2715.  
  2716.  
  2717.           4.3  setpw
  2718.  
  2719.           ■ Summary
  2720.  
  2721.           C          _
  2722.  
  2723.           #include <ioctl.h>
  2724.  
  2725.           extern void pascal far setpw(unsigned char *pw);
  2726.  
  2727.           BASIC          _____
  2728.  
  2729.           DECLARE SUB SETPW(BYVAL S AS INTEGER)
  2730.  
  2731.           A$ = "MyPasswd"
  2732.           CALL SETPW(SADD(A$))
  2733.  
  2734.           Note  that A$ must be at least 8 characters long.  Only the first
  2735.           8 characters will be used.
  2736.  
  2737.           FORTRAN          _______
  2738.  
  2739.           CHARACTER*8 PW
  2740.  
  2741.           PW = "MyPasswd"
  2742.           CALL SETPW(PW)
  2743.  
  2744.           ■  Description
  2745.  
  2746.           The setpw  function sets  the password to  be used  on subsequent
  2747.           calls to any  of the following functions.   These functions auto-
  2748.           matically  supply  the  most   recent  password  when  they  call
  2749.           CLOCK.SYS.   You need not  ever call setpw  if you are  not using
  2750.           password protection.  CLOCK.SYS will  only check the password  if
  2751.           password protection is enabled through the stmode function.
  2752.  
  2753.           ■ Arguments         pw
  2754.                                    is  a  pointer to  the  password string.
  2755.                                    This string should be exactly 8  charac-
  2756.                                    ters long and must be at least 8 charac-
  2757.                                    ters long.   The password should also be
  2758.                                    LJSF as every  character is significant.
  2759.                                    Case is significant in passwords.
  2760.  
  2761.  
  2762.  
  2763.  
  2764.  
  2765.  
  2766.  
  2767.                                           39
  2768.  
  2769.  
  2770.  
  2771.  
  2772.  
  2773.  
  2774.  
  2775.  
  2776.  
  2777.  
  2778.  
  2779.  
  2780.           CLOCK Version 3.44                                  March 9, 1993
  2781.  
  2782.  
  2783.           ■  Example
  2784.  
  2785.           #include <ioctl.h>
  2786.  
  2787.           main()
  2788.  
  2789.           {
  2790.                   unsigned char pw[9] = "MyPasswd";
  2791.  
  2792.           /* Set password to use on subsequent function calls.  */
  2793.  
  2794.                   setpw(pw);
  2795.  
  2796.           }
  2797.  
  2798.  
  2799.           4.4  connec
  2800.  
  2801.           ■  Summary
  2802.  
  2803.           C          _
  2804.  
  2805.           #include <ioctl.h>
  2806.  
  2807.           extern int pascal far connec(int *conn);
  2808.  
  2809.           BASIC          _____
  2810.  
  2811.           DECLARE FUNCTION CONNEC%(CONN AS INTEGER)
  2812.  
  2813.           STATUS% = CONNEC(CONN)
  2814.  
  2815.           FORTRAN          _______
  2816.  
  2817.           INTEGER*2 CONN, STATUS, CONNEC
  2818.  
  2819.           STATUS = CONNEC(CONN)
  2820.  
  2821.           ■  Description
  2822.  
  2823.           The connec function  provides a means  of setting the  connection
  2824.           state of CLOCK.SYS.
  2825.  
  2826.  
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.  
  2833.                                           40
  2834.  
  2835.  
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.  
  2843.  
  2844.  
  2845.  
  2846.           CLOCK Version 3.44                                  March 9, 1993
  2847.  
  2848.  
  2849.           ■  Arguments   conn
  2850.                               specifies the new connection mode.  The  val-
  2851.                               ues are:
  2852.                               0 = disconnected (C=D)
  2853.                               1 = connected for writes only (C=W)
  2854.                               2 = connected for  writes and periodic  reads
  2855.                               (C=R)
  2856.                               3 = connected for all operations (C=A)
  2857.  
  2858.  
  2859.           ■ Return Value
  2860.  
  2861.           If  the return  value is zero,  the function  succeeded.   If the
  2862.           return value is non-zero, an error has occurred and _doserrno  is
  2863.           set to the corresponding error code.  Possible values are:
  2864.  
  2865.                0001h     Invalid  function.    This  should  indicate  that
  2866.                          CLOCK.SYS is  not installed.  It is the error that
  2867.                          the DOS clock device  driver would return since it
  2868.                          doesn't handle these functions.
  2869.  
  2870.                0005h     Access denied.  Indicates  that DOS would not open
  2871.                          a handle for read access.  You may not have enough
  2872.                          handles available.
  2873.  
  2874.                0006h     Invalid handle.  Should not happen.
  2875.  
  2876.                000Dh     Invalid data.  CLOCK.SYS reported a bad byte count
  2877.                          or otherwise  did not  process the request.   This
  2878.                          should not happen.
  2879.  
  2880.           ■  Example
  2881.  
  2882.           #include <stdio.h>
  2883.           #include <ioctl.h>
  2884.  
  2885.           main()
  2886.           {
  2887.                int conn_write = 1;
  2888.                int status;
  2889.  
  2890.           /* Set clock to connected for writes */
  2891.  
  2892.                status = connec(&conn_write);
  2893.                if (status)
  2894.                     printf("Error %X in connec\n", status);
  2895.           }
  2896.  
  2897.  
  2898.  
  2899.                                           41
  2900.  
  2901.  
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.  
  2910.  
  2911.  
  2912.           CLOCK Version 3.44                                  March 9, 1993
  2913.  
  2914.  
  2915.           4.5  newpw
  2916.  
  2917.           ■  Summary
  2918.  
  2919.           C          _
  2920.  
  2921.           #include <ioctl.h>
  2922.  
  2923.           extern int pascal far newpw(unsigned char *pw);
  2924.  
  2925.           BASIC          _____
  2926.  
  2927.           DECLARE FUNCTION NEWPW%(BYVAL S AS INTEGER)
  2928.  
  2929.           A$ = "MyPasswd"
  2930.           STATUS% = NEWPW(SADD(A$))
  2931.  
  2932.           Note  that A$ must be at least 8 characters long.  Only the first
  2933.           8 characters will be used.
  2934.  
  2935.           FORTRAN          _______
  2936.  
  2937.           CHARACTER*8 PW
  2938.           INTEGER*2 STATUS, NEWPW
  2939.  
  2940.           PW = "MyPasswd"
  2941.           STATUS = NEWPW(PW)
  2942.  
  2943.           ■  Description
  2944.  
  2945.           The  newpw function  sets a  new  password for  CLOCK.SYS.   This
  2946.           function is not  sufficient to enable  password protection.   You
  2947.           must  also use stmode to  turn on password checking.   BE SURE to
  2948.           use newpw before you use stmode to turn on password checking.  If
  2949.           you turn on password checking without first setting the  password
  2950.           to something  that you know,  you will never  be able to  use the
  2951.           CLOCK.SYS functions again until you reboot.
  2952.  
  2953.           ■ Arguments         pw
  2954.                                    is  a pointer  to  the password  string.
  2955.                                    This string should be  exactly 8 charac-
  2956.                                    ters long and must be at least 8 charac-
  2957.                                    ters long.  The  password should also be
  2958.                                    LJSF as every  character is significant.
  2959.                                    Case is significant in passwords.
  2960.  
  2961.           ■ Return Value
  2962.  
  2963.  
  2964.  
  2965.                                           42
  2966.  
  2967.  
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.  
  2975.  
  2976.  
  2977.  
  2978.           CLOCK Version 3.44                                  March 9, 1993
  2979.  
  2980.  
  2981.           If  the return value  is zero,  the function  succeeded.   If the
  2982.           return value is non-zero, an error has occurred and _doserrno  is
  2983.           set to the corresponding error code.  Possible values are:
  2984.  
  2985.                0001h     Invalid  function.    This  should  indicate  that
  2986.                          CLOCK.SYS is not installed.   It is the error that
  2987.                          the DOS clock device  driver would return since it
  2988.                          doesn't handle these functions.
  2989.  
  2990.                0005h     Access denied.  Indicates  that DOS would not open
  2991.                          a handle for read access.  You may not have enough
  2992.                          handles available.
  2993.  
  2994.                0006h     Invalid handle.  Should not happen.
  2995.  
  2996.                000Dh     Invalid data.  CLOCK.SYS reported a bad byte count
  2997.                          or otherwise  did not  process the request.   This
  2998.                          should not happen.
  2999.  
  3000.  
  3001.           ■  Example
  3002.  
  3003.           #include <stdio.h>
  3004.           #include <ioctl.h>
  3005.  
  3006.           main()
  3007.  
  3008.           {
  3009.                   unsigned char pw[9] = "MyPasswd";
  3010.                  int status;
  3011.  
  3012.           /* Set new password for CLOCK.SYS  */
  3013.  
  3014.                   status = setpw(pw);
  3015.                  if (status)
  3016.                     printf("Error %X in setpw\n", status);
  3017.  
  3018.           }
  3019.  
  3020.  
  3021.           4.6  rstrct
  3022.  
  3023.  
  3024.  
  3025.  
  3026.  
  3027.  
  3028.  
  3029.  
  3030.  
  3031.                                           43
  3032.  
  3033.  
  3034.  
  3035.  
  3036.  
  3037.  
  3038.  
  3039.  
  3040.  
  3041.  
  3042.  
  3043.  
  3044.           CLOCK Version 3.44                                  March 9, 1993
  3045.  
  3046.  
  3047.           ■  Summary
  3048.  
  3049.           C          _
  3050.  
  3051.           #include <ioctl.h>
  3052.  
  3053.           extern int pascal far rstrct(int *bhour, int *bmin, int *bsec,
  3054.               int *fhour, int *fmin, int *fsec);
  3055.  
  3056.           BASIC          _____
  3057.  
  3058.           DECLARE  FUNCTION RSTRCT%(BHOUR%,  BMIN%,  BSEC%, FHOUR%,  FMIN%,
  3059.           FSEC%)
  3060.  
  3061.           FORTRAN          _______
  3062.  
  3063.           INTEGER*2 BHOUR, BMIN, BSEC, FHOUR, FMIN, FSEC
  3064.           INTEGER*2 RSTRCT
  3065.  
  3066.           STATUS = RSTRCT(BHOUR, BMIN, BSEC, FHOUR, FMIN, FSEC)
  3067.  
  3068.           ■  Description
  3069.  
  3070.           The rstrct  function sets backwards  and forwards limits  on time
  3071.           changes.   Any  time changes  that  exceed these  limits will  be
  3072.           ignored.  For example,  if a backward limit of 2  seconds is set,
  3073.           no change that would move the clock backwards more than 2 seconds
  3074.           will be processed.  Setting the limits protects you agains keying
  3075.           in a  bad time and  agains programs that may  incorrectly set the
  3076.           time.  Yet you  can still change  the time within the  prescribed
  3077.           limits.  For  example, you may set a backward  limit of 2 seconds
  3078.           to permit CLK to adjust the time  by up to 2 seconds while inhib-
  3079.           iting any other  backwards changes.  These limits  have no effect
  3080.           on changing between standard  and daylight times  as that is  not
  3081.           really a change in the "time".
  3082.  
  3083.           ■ Arguments         bhour:bmin:bsec
  3084.                                    is the backward limit  in hours, minutes
  3085.                                    and seconds.
  3086.  
  3087.                               fhour:fmin:fsec
  3088.                                    is the forward limit in hours,  minutes,
  3089.                                    and seconds.
  3090.  
  3091.           ■ Return Value
  3092.  
  3093.  
  3094.  
  3095.  
  3096.  
  3097.                                           44
  3098.  
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.  
  3107.  
  3108.  
  3109.  
  3110.           CLOCK Version 3.44                                  March 9, 1993
  3111.  
  3112.  
  3113.           If  the return value  is zero,  the function  succeeded.   If the
  3114.           return value is non-zero, an error has occurred and _doserrno  is
  3115.           set to the corresponding error code.  Possible values are:
  3116.  
  3117.                0001h     Invalid  function.    This  should  indicate  that
  3118.                          CLOCK.SYS is not installed.   It is the error that
  3119.                          the DOS clock device  driver would return since it
  3120.                          doesn't handle these functions.
  3121.  
  3122.                0005h     Access denied.  Indicates  that DOS would not open
  3123.                          a handle for read access.  You may not have enough
  3124.                          handles available.
  3125.  
  3126.                0006h     Invalid handle.  Should not happen.
  3127.  
  3128.                000Dh     Invalid data.  CLOCK.SYS reported a bad byte count
  3129.                          or otherwise  did not  process the request.   This
  3130.                          should not happen.
  3131.  
  3132.  
  3133.           ■  Example
  3134.  
  3135.           #include <stdio.h>
  3136.           #include <ioctl.h>
  3137.  
  3138.           main()
  3139.  
  3140.           {
  3141.                int bhour = 0;
  3142.                int bmin = 0;
  3143.                int bsec = 2;
  3144.                int fhour = 1;
  3145.                int fmin = 0;
  3146.                int fsec = 0;
  3147.                int status;
  3148.  
  3149.           /* Set  time change  limits to  2 seconds  backwards  and 1  hour
  3150.           forwards  */
  3151.  
  3152.                status = rstrct(&bhour, &bmin, &bsec, &fhour, &fmin, &fsec);
  3153.                if (status)
  3154.                     printf("Error %X in rstrct\n", status);
  3155.                else
  3156.                     printf("Time limits set to "
  3157.                          "-%.2d:%.2d:%.2d,+%.2d:%.2d:%.2d\n",
  3158.                          bhour, bmin, bsec, fhour, fmin, fsec);
  3159.           }
  3160.  
  3161.  
  3162.  
  3163.                                           45
  3164.  
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.  
  3173.  
  3174.  
  3175.  
  3176.           CLOCK Version 3.44                                  March 9, 1993
  3177.  
  3178.  
  3179.           4.7  stmode
  3180.  
  3181.           ■  Summary
  3182.  
  3183.           C          _
  3184.  
  3185.           #include <ioctl.h>
  3186.  
  3187.           extern int pascal far stmode(struct modes *mode);
  3188.  
  3189.           BASIC          _____
  3190.  
  3191.           DECLARE FUNCTION STMODE%(MODES%)
  3192.  
  3193.           FORTRAN          _______
  3194.  
  3195.           INTEGER*2 MODES
  3196.           INTEGER*2 STMODE
  3197.  
  3198.           STATUS = STMODE(MODES)
  3199.  
  3200.           ■  Description
  3201.  
  3202.           The  stmode function  sets a  variety  of operating  modes.   The
  3203.           argument is  actually a  structure of bits.   Each  bit specifies
  3204.           whether an operating mode is on (1) or off (0).
  3205.  
  3206.           ■ Arguments         modes
  3207.                                    is set  of bits  that specify  operating
  3208.                                    modes.  The bit values are:
  3209.  
  3210.                                    unsigned : 9;            Unused
  3211.                                    unsigned day_light: 1;   0x0200 (512)
  3212.                                    unsigned disp_24 : 1;    0x0400 (1024)
  3213.                                    unsigned disp_tim : 1;   0x0800 (2048)
  3214.                                    unsigned pw_ena : 1;     0x1000 (4096)
  3215.                                    unsigned disabl : 1;     0x2000 (8192)
  3216.                                    unsigned chk_forw : 1;   0x4000 (16384)
  3217.                                    unsigned chk_back : 1;   0x8000 (32768)
  3218.  
  3219.           ■ Return Value
  3220.  
  3221.           If the  return value  is zero,  the function  succeeded.  If  the
  3222.           return value is non-zero, an error has occurred and _doserrno  is
  3223.           set to the corresponding error code.  Possible values are:
  3224.  
  3225.                0001h     Invalid  function.    This  should  indicate  that
  3226.                          CLOCK.SYS is not installed.  It is the  error that
  3227.  
  3228.  
  3229.                                           46
  3230.  
  3231.  
  3232.  
  3233.  
  3234.  
  3235.  
  3236.  
  3237.  
  3238.  
  3239.  
  3240.  
  3241.  
  3242.           CLOCK Version 3.44                                  March 9, 1993
  3243.  
  3244.  
  3245.                          the DOS clock device  driver would return since it
  3246.                          doesn't handle these functions.
  3247.  
  3248.                0005h     Access denied.  Indicates  that DOS would not open
  3249.                          a handle for read access.  You may not have enough
  3250.                          handles available.
  3251.  
  3252.                0006h     Invalid handle.  Should not happen.
  3253.  
  3254.                000Dh     Invalid data.  CLOCK.SYS reported a bad byte count
  3255.                          or otherwise  did not  process the request.   This
  3256.                          should not happen.
  3257.  
  3258.  
  3259.           ■  Example
  3260.  
  3261.           #include <ioctl.h>
  3262.  
  3263.           main()
  3264.  
  3265.           {
  3266.                struct CLOCK_DATA cdata;
  3267.  
  3268.           /* Set daylight savings time.  */
  3269.  
  3270.                clksta(&cdata);            /* Get current mode settings. */
  3271.  
  3272.                cdata.mode.day_light = 1;  /* Turn on daylight */
  3273.  
  3274.                stmode(&cdata.modes);
  3275.           }
  3276.  
  3277.  
  3278.           4.8  stzone
  3279.  
  3280.           ■  Summary
  3281.  
  3282.           C          _
  3283.  
  3284.           #include <ioctl.h>
  3285.  
  3286.           extern int pascal far stzone(int *shour, int *smin, int *ssec,
  3287.               unsigned char sname[32], int *dhour, int *dmin,
  3288.               int *dsec, unsigned char dname[32]);
  3289.  
  3290.  
  3291.  
  3292.  
  3293.  
  3294.  
  3295.                                           47
  3296.  
  3297.  
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304.  
  3305.  
  3306.  
  3307.  
  3308.           CLOCK Version 3.44                                  March 9, 1993
  3309.  
  3310.  
  3311.           BASIC          _____
  3312.  
  3313.           DECLARE  FUNCTION  STZONE%(SHOUR%,  SMIN%,  SSEC%,  BYVAL  SN  AS
  3314.           INTEGER, DHOUR%, DMIN%, DSEC%, BYVAL DN AS INTEGER)
  3315.  
  3316.           SNAME$ = "32-CHARACTER STANDARD ZONE NAME "
  3317.           DNAME$ = "Daylight savings time zone name "
  3318.  
  3319.           STATUS% = STZONE(6,0,0,SADD(SNAME$),5,0,0,SADD(DNAME$))
  3320.  
  3321.           FORTRAN          _______
  3322.  
  3323.           CHARACTER*32 SNAME, DNAME
  3324.           INTEGER*2 STZONE, STATUS
  3325.  
  3326.           SNAME = "CST"
  3327.           DNAME = "CDT"
  3328.           STATUS = STZONE(6, 0, 0, SNAME, 5, 0, 0, DNAME)
  3329.  
  3330.           ■  Description
  3331.  
  3332.           The stzone function  sets the standard time and  daylight savings
  3333.           time offsets from the  calendar clock and  the standard and  day-
  3334.           light time zone  names or mnemonics.   Note that the  offsets are
  3335.           subtracted from the calendar  clock to get the local  time.  Thus
  3336.           the standard time offset from UTC to EST is 5:0:0.
  3337.  
  3338.           ■ Arguments         SHOUR:SMIN:SSEC
  3339.                                    is the time difference  between the cal-
  3340.                                    endar clock and local standard time.  It
  3341.                                    may be a positive of negative value.  If
  3342.                                    negative, all three values must be nega-
  3343.                                    tive.
  3344.  
  3345.                               SNAME
  3346.                                    is the  standard time zone name  or mne-
  3347.                                    monic.   It must be  a 32-character LJSF
  3348.                                    character  string.   As  with  all other
  3349.                                    character  strings used  by these  func-
  3350.                                    tions,  there  is  no  terminating  NULL
  3351.                                    character as  is usual in C.   The other
  3352.                                    languages  do  not readily  handle  NULL
  3353.                                    terminated strings.   In  C applications
  3354.                                    you may  define the  character array  to
  3355.                                    contain  33  characters,  but  you  must
  3356.                                    ensure that the  NULL character does not
  3357.                                    occur in the first 32 characters.
  3358.  
  3359.  
  3360.  
  3361.                                           48
  3362.  
  3363.  
  3364.  
  3365.  
  3366.  
  3367.  
  3368.  
  3369.  
  3370.  
  3371.  
  3372.  
  3373.  
  3374.           CLOCK Version 3.44                                  March 9, 1993
  3375.  
  3376.  
  3377.                               DHOUR:DMIN:DSEC
  3378.                                    is the time difference  between the cal-
  3379.                                    endar clock  and local  daylight savings
  3380.                                    time.   Whether  the standard  offset or
  3381.                                    the daylight offset is currently used by
  3382.                                    CLOCK.SYS is  controlled by  the setting
  3383.                                    of the day_light mode bit (see stmode).
  3384.  
  3385.                               DNAME
  3386.                                    is the  daylight savings time  zone name
  3387.                                    or  mnemonic.  It must be a 32-character
  3388.                                    LJSF character string.
  3389.  
  3390.           ■ Return Value
  3391.  
  3392.           If the  return value  is zero,  the function  succeeded.   If the
  3393.           return value is non-zero, an error has occurred and _doserrno  is
  3394.           set to the corresponding error code.  Possible values are:
  3395.  
  3396.                0001h     Invalid  function.    This  should  indicate  that
  3397.                          CLOCK.SYS is not installed.  It is the  error that
  3398.                          the DOS clock device  driver would return since it
  3399.                          doesn't handle these functions.
  3400.  
  3401.                0005h     Access denied.  Indicates  that DOS would not open
  3402.                          a handle for read access.  You may not have enough
  3403.                          handles available.
  3404.  
  3405.                0006h     Invalid handle.  Should not happen.
  3406.  
  3407.                000Dh     Invalid data.  CLOCK.SYS reported a bad byte count
  3408.                          or otherwise  did not  process the request.   This
  3409.                          should not happen.
  3410.  
  3411.  
  3412.  
  3413.  
  3414.  
  3415.  
  3416.  
  3417.  
  3418.  
  3419.  
  3420.  
  3421.  
  3422.  
  3423.  
  3424.  
  3425.  
  3426.  
  3427.                                           49
  3428.  
  3429.  
  3430.  
  3431.  
  3432.  
  3433.  
  3434.  
  3435.  
  3436.  
  3437.  
  3438.  
  3439.  
  3440.           CLOCK Version 3.44                                  March 9, 1993
  3441.  
  3442.  
  3443.           ■  Example
  3444.  
  3445.           #include <stdio.h>
  3446.           #include <ioctl.h>
  3447.  
  3448.           main()
  3449.  
  3450.           {
  3451.                unsigned char sname[33] = "PST                    ";
  3452.                unsigned char dname[33] = "PDT                    ";
  3453.                int shour = 8;
  3454.                int smin = 0;
  3455.                int ssec = 0;
  3456.                int dhour = 7;
  3457.                int dmin = 0;
  3458.                int dsec = 0;
  3459.                struct CLOCK_DATA cdata;
  3460.  
  3461.           /* Get current status.   */
  3462.  
  3463.                clksta(&cdata);
  3464.  
  3465.           /* Set time zone to U.S. Pacific time.  */
  3466.  
  3467.                stzone(&shour, &smin, &ssec, sname, &dhour, &dmin, &dsec,
  3468.                    dname);
  3469.  
  3470.           /* Select daylight savings time.  */
  3471.  
  3472.                cdata.mode.day_light = 1;
  3473.                stmode(&cdata.mode);
  3474.           }
  3475.  
  3476.  
  3477.           4.9  tdisp
  3478.  
  3479.           ■  Summary
  3480.  
  3481.           C          _
  3482.  
  3483.           #include <ioctl.h>
  3484.  
  3485.           extern int pascal far tdisp(int *dispx, int *dispy, int *attr);
  3486.  
  3487.  
  3488.  
  3489.  
  3490.  
  3491.  
  3492.  
  3493.                                           50
  3494.  
  3495.  
  3496.  
  3497.  
  3498.  
  3499.  
  3500.  
  3501.  
  3502.  
  3503.  
  3504.  
  3505.  
  3506.           CLOCK Version 3.44                                  March 9, 1993
  3507.  
  3508.  
  3509.           BASIC          _____
  3510.  
  3511.           DECLARE FUNCTION TDISP%(DISPX%, DISPY%, ATTR%)
  3512.  
  3513.           STATUS% = TDISP(72, 0, &H79)
  3514.  
  3515.           FORTRAN          _______
  3516.  
  3517.           INTEGER*2 TDISP, STATUS
  3518.  
  3519.           STATUS = TDISP(0, 72, 0x79)
  3520.  
  3521.           ■  Description
  3522.  
  3523.           The tdisp  function sets  the coordinates  and attribute  for the
  3524.           continuous time  display.   tdisp  does  not start  or  stop  the
  3525.           continuous display nor  does it set the 12-hour  or 24-hour mode.
  3526.           Those are all provided by the stmode function.
  3527.  
  3528.           ■ Arguments         DISPX
  3529.                                    is the x  (horizontal) cursor coordinate
  3530.                                    for  the continuous  time display.   The
  3531.                                    rightmost character on a line is at x=0.
  3532.                                    Be sure to leave enough space at the end
  3533.                                    of the line to accommodate the entire 8-
  3534.                                    chararacter time display.   For example,
  3535.                                    x=72 is  the last position to specify on
  3536.                                    an 80-character line.
  3537.  
  3538.                               DISPY
  3539.                                    is  the y  (vertical) cursor  coordinate
  3540.                                    for the  continuous time  display.   The
  3541.                                    top line on the display is y=0.
  3542.  
  3543.                               ATTR
  3544.                                    is the display attribute  to use for the
  3545.                                    continuous time display.  ATTR is usual-
  3546.                                    ly  expressed as  two hex  digits.   The
  3547.                                    first  (high-order) digit  is the  back-
  3548.                                    ground  color  (0 to  7) and  the second
  3549.                                    digit is the text or foreground color (0
  3550.                                    to  F).  For  example, 0A  would display
  3551.                                    bright  green letters  on a  black back-
  3552.                                    ground.   Background  colors usually  do
  3553.                                    not include  the  bright  colors.    The
  3554.                                    color numbers are:
  3555.  
  3556.  
  3557.  
  3558.  
  3559.                                           51
  3560.  
  3561.  
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.  
  3570.  
  3571.  
  3572.           CLOCK Version 3.44                                  March 9, 1993
  3573.  
  3574.  
  3575.                                         0    Black
  3576.                                         1    Blue
  3577.                                         2    Green
  3578.                                         3    Cyan
  3579.                                         4    Red
  3580.                                         5    Magenta
  3581.                                         6    Brown
  3582.                                         7    White
  3583.                                         8    Grey
  3584.                                         9    Bright blue
  3585.                                         A    Bright green
  3586.                                         B    Brigth cyan
  3587.                                         C    Bright red
  3588.                                         D    Bright magenta
  3589.                                         E    Yellow
  3590.                                         F    Bright White
  3591.  
  3592.           ■ Return Value
  3593.  
  3594.           If the  return value  is zero,  the function succeeded.   If  the
  3595.           return value is non-zero, an error has occurred and _doserrno  is
  3596.           set to the corresponding error code.  Possible values are:
  3597.  
  3598.                0001h     Invalid  function.    This  should  indicate  that
  3599.                          CLOCK.SYS is not installed.  It is  the error that
  3600.                          the DOS clock device  driver would return since it
  3601.                          doesn't handle these functions.
  3602.  
  3603.                0005h     Access denied.  Indicates  that DOS would not open
  3604.                          a handle for read access.  You may not have enough
  3605.                          handles available.
  3606.  
  3607.                0006h     Invalid handle.  Should not happen.
  3608.  
  3609.                000Dh     Invalid data.  CLOCK.SYS reported a bad byte count
  3610.                          or otherwise  did not  process the request.   This
  3611.                          should not happen.
  3612.  
  3613.  
  3614.  
  3615.  
  3616.  
  3617.  
  3618.  
  3619.  
  3620.  
  3621.  
  3622.  
  3623.  
  3624.  
  3625.                                           52
  3626.  
  3627.  
  3628.  
  3629.  
  3630.  
  3631.  
  3632.  
  3633.  
  3634.  
  3635.  
  3636.  
  3637.  
  3638.           CLOCK Version 3.44                                  March 9, 1993
  3639.  
  3640.  
  3641.           ■  Example
  3642.  
  3643.           #include <stdio.h>
  3644.           #include <ioctl.h>
  3645.  
  3646.           main()
  3647.  
  3648.           {
  3649.                struct CLOCK_DATA cdata;
  3650.                int dispx = 72;
  3651.                int dispy = 0;
  3652.                int attr = 0x79;
  3653.  
  3654.           /* Get current CLOCK.SYS modes.  */
  3655.  
  3656.                clksta(&cdata);
  3657.  
  3658.           /* Turn on 12-hour display at end of top line of screen. 
  3659.              Use bright blue text on a white backgroun.          */
  3660.  
  3661.                tdisp(&dispx, &dispy, &attr);
  3662.                cdata.mode.disp_tim = 1;
  3663.                cdata.mode.disp_24 = 0;
  3664.                stmode(&cdata.mode);
  3665.  
  3666.           }
  3667.  
  3668.  
  3669.  
  3670.  
  3671.  
  3672.  
  3673.  
  3674.  
  3675.  
  3676.  
  3677.  
  3678.  
  3679.  
  3680.  
  3681.  
  3682.  
  3683.  
  3684.  
  3685.  
  3686.  
  3687.  
  3688.  
  3689.  
  3690.  
  3691.                                           53
  3692.  
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.  
  3702.  
  3703.  
  3704.           CLOCK Version 3.44                                  March 9, 1993
  3705.  
  3706.  
  3707.           5  CLOCK.SYS - ASSEMBLY LANGUAGE API
  3708.  
  3709.           CLOCK.SYS has  a couple of additional  APIs (Application Program-
  3710.           ming Interfaces) that are  not present in  the normal DOS  CLOCK$
  3711.           device driver.  These  interfaces are provided  by the DOS  IOCTL
  3712.           (Input/Output  of ConTroL  data) functions.   The  Output Control
  3713.           Data to Character Device  function is used  to set new  operating
  3714.           values for CLOCK.SYS  for the C=, D=, R=,  TZ=, and /P functions.
  3715.           The Input Control Data from Character Device function is used  to
  3716.           get the current status  and the date and  time from the  calendar
  3717.           clock.
  3718.  
  3719.  
  3720.           5.1  Opening the CLOCK$ Device
  3721.  
  3722.           In order  to use  the additional APIs  provided by  CLOCK.SYS you
  3723.           must  open a handle  to the  CLOCK$ device driver.   You  do this
  3724.           using the  DOS  INT 21H  Open  File with  Handle  (3DH)  function
  3725.           specifying read-write access.  You then use the handle to  invoke
  3726.           the other functions.  Sample assembly language is:
  3727.                MOV  AX,3D00H            ; Open with read and write access
  3728.                MOV  DX,OFFSET filename  ; Pointer to "CLOCK$" ASCIIZ string
  3729.                                         ; DS:DX must point to the string
  3730.                INT  21H                 ; Call DOS function handler
  3731.           ;    AX contains the handle on return if carry flag is not set.
  3732.  
  3733.  
  3734.           5.2  Sending New Values to CLOCK.SYS
  3735.  
  3736.           To change the  state of CLOCK.SYS, you use  the Send Control Data
  3737.           to  Character Device  (4403H) DOS  function.   You  send data  to
  3738.           specify the connection  type, modes, time zone offsets and names,
  3739.           restrictions, continuous display information, and  password.  You
  3740.           may send any combination of these  in any order.  You must always
  3741.           send  the current  password as the  first 8  bytes.   If password
  3742.           checking  is not  enabled, it  doesn't  matter what  the 8  bytes
  3743.           contain, but you must still send the 8 bytes.
  3744.  
  3745.           The data  stream  that you  send  to CLOCK.SYS  consists  of  the
  3746.           current password followed by a selection index, the data for that
  3747.           selection, another selection index, its data, and so on.
  3748.  
  3749.  
  3750.  
  3751.  
  3752.  
  3753.  
  3754.  
  3755.  
  3756.  
  3757.                                           54
  3758.  
  3759.  
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.  
  3768.  
  3769.  
  3770.           CLOCK Version 3.44                                  March 9, 1993
  3771.  
  3772.  
  3773.           The selection  indices and the  data stream associated  with each
  3774.           one are:
  3775.  
  3776.           INDEX     DATA ITEMS     COMMENTS          _____     __________     ________
  3777.  
  3778.           1         connected      two  byte   integer  (0 : C=D,  1 : C=W,
  3779.                                    2 : C=R, 3 : C=A)
  3780.  
  3781.           2         mode           two byte  integer (see stmode  for a de-
  3782.                                    scription of the bits)
  3783.  
  3784.           3         standard       time_zone structure for standard time
  3785.                     daylight       time_zone structure for daylight time
  3786.  
  3787.           4         rules          limits structure
  3788.  
  3789.           5         display        disp structure
  3790.  
  3791.           6         password       8 bytes LJSF of new password
  3792.  
  3793.           Sample assembly language to send new information to CLOCK.SYS:
  3794.  
  3795.           curpw     DB   8 dup(?)       ; Current password
  3796.                     DW   1              ; Change connection
  3797.                     DW   2              ;  to C=R
  3798.                     DW   4              ; Change limits
  3799.                     DW   0,0,2,1,0,0    ;  to R=B-::2,F+1
  3800.                     DW   6              ; Set new password
  3801.                     DB   "MyPasswd"     ;  to MyPasswd (case is important)
  3802.                     DW   2              ; Change modes
  3803.                     DW   0D000H         ;  to enable limits and password
  3804.                                         ;  also sets standard time and 
  3805.                                         ;  no display
  3806.           count     equ $-curpw         ; Length to send
  3807.                ...
  3808.                     MOV  AX,4403H       ; Send control data function
  3809.                     MOV  BX,handle      ; Value returned from open
  3810.                     MOV  CX,count       ; Value = number of bytes to send
  3811.                     MOV  DX,OFFSET curpw ; Location of bytes to be sent
  3812.                                         ; DS:DX must point to the buffer
  3813.                     INT  21H            ;
  3814.           ; OK if carry not set.  CX will equal bytes actually taken.
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.  
  3821.  
  3822.  
  3823.                                           55
  3824.  
  3825.  
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832.  
  3833.  
  3834.  
  3835.  
  3836.           CLOCK Version 3.44                                  March 9, 1993
  3837.  
  3838.  
  3839.           5.3  Getting Current Status of CLOCK.SYS
  3840.  
  3841.           To get the current  status and time, you use  the Receive Control
  3842.           Data from Character Device (4402H) function.  You can read all of
  3843.           the CLOCK_DATA  structure or  any smaller amount  of it  that you
  3844.           need, but you can only read starting at the beginning
  3845.  
  3846.           Sample assembly language for reading the clock status is:
  3847.  
  3848.                MOV  AX,440CH            ; Read control data function
  3849.                MOV  BX,handle           ; Value returned from open
  3850.                MOV  CX,count            ; Number of bytes to read
  3851.                MOV  DX,OFFSET buffer    ; Location to store the data
  3852.                                         ; DS:DX must point to the buffer
  3853.                INT  21H                 ; Call DOS
  3854.           ; Data returned if carry not set.
  3855.           ; CX will contain the actual number of bytes transferred.
  3856.  
  3857.  
  3858.  
  3859.  
  3860.  
  3861.  
  3862.  
  3863.  
  3864.  
  3865.  
  3866.  
  3867.  
  3868.  
  3869.  
  3870.  
  3871.  
  3872.  
  3873.  
  3874.  
  3875.  
  3876.  
  3877.  
  3878.  
  3879.  
  3880.  
  3881.  
  3882.  
  3883.  
  3884.  
  3885.  
  3886.  
  3887.  
  3888.  
  3889.                                           56
  3890.  
  3891.  
  3892.  
  3893.  
  3894.  
  3895.  
  3896.  
  3897.  
  3898.  
  3899.  
  3900.  
  3901.  
  3902.           CLOCK Version 3.44                                  March 9, 1993
  3903.  
  3904.  
  3905.           APPENDIX A:  DEFINITION OF SHAREWARE
  3906.  
  3907.           Shareware  distribution  gives users  a  chance  to try  software
  3908.           before buying  it. If  you try a  Shareware program  and continue
  3909.           using  it,  you are  expected  to  register. Individual  programs
  3910.           differ  on  details --  some  request  registration while  others
  3911.           require it, some specify a maximum trial period.  With  registra-
  3912.           tion, you get anything  from the simple  right to continue  using
  3913.           the software to an updated program with printed manual.
  3914.  
  3915.           Copyright laws  apply to both Shareware  and commercial software,
  3916.           and the copyright holder retains all rights, with a few  specific
  3917.           exceptions as  stated below.  Shareware authors are  accomplished
  3918.           programmers, just  like commercial authors, and  the programs are
  3919.           of comparable  quality. (In both  cases, there are  good programs
  3920.           and bad ones!) The main difference  is in the method of distribu-
  3921.           tion.  The author  specifically  grants  the  right to  copy  and
  3922.           distribute the software, either to all and sundry or to a specif-
  3923.           ic group.  For example,  some authors require  written permission
  3924.           before a commercial disk vendor may copy their Shareware.
  3925.  
  3926.           Shareware is a  distribution method, not a type  of software. You
  3927.           should  find  software  that  suits your  needs  and  pocketbook,
  3928.           whether it's commercial or  Shareware. The Shareware system makes
  3929.           fitting your needs easier,  because you can  try before you  buy.
  3930.           And because the  overhead is low, prices are  low also. Shareware
  3931.           has the  ultimate money-back  guarantee -- if  you don't  use the
  3932.           product, you don't pay for it.
  3933.  
  3934.           DISCLAIMER - AGREEMENT
  3935.  
  3936.           Users of CLOCK  must accept this disclaimer of  warranty:  "CLOCK
  3937.           is supplied  as is.   The  author disclaims  all warranties,  ex-
  3938.           pressed or implied, including, without limitation, the warranties
  3939.           of merchantability and of  fitness for any  purpose.  The  author
  3940.           assumes no liability for  damages, direct or consequential, which
  3941.           may result from the use of CLOCK."
  3942.  
  3943.           CLOCK is a  "shareware program" and is  provided at no charge  to
  3944.           the  user for  evaluation.   Feel  free  to  share it  with  your
  3945.           friends, but please  do not give  it away altered  or as part  of
  3946.           another system.   The essence of "user-supported"  software is to
  3947.           provide  personal computer  users with  quality software  without
  3948.           high prices,  and yet  to  provide incentive  for programmers  to
  3949.           continue  to develop  new products.    If you  find this  program
  3950.           useful  and find  that you are  using CLOCK  and continue  to use
  3951.           CLOCK after a reasonable trial period, you must make a  registra-
  3952.           tion payment of $10 to Ronald Q. Smith.  The $10 registration fee
  3953.  
  3954.  
  3955.                                           57
  3956.  
  3957.  
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.  
  3965.  
  3966.  
  3967.  
  3968.           CLOCK Version 3.44                                  March 9, 1993
  3969.  
  3970.  
  3971.           will license  one copy  for use  on any one  computer at  any one
  3972.           time.  For a registration fee of $25, I will immediately send you
  3973.           the latest version of  CLOCK including the  source code and  this
  3974.           document as a WordPerfect 5.1 file.   You may use the source code
  3975.           for your own maintenance  of CLOCK or as a learning  tool for any
  3976.           software that you  develop.  You may  not use all or  part of the
  3977.           source code in any software that you develop or release to others
  3978.           without the permission of Ronald Q. Smith.
  3979.  
  3980.           You must  treat this software  just like a  book.  An  example is
  3981.           that this software may be used by any number of people and may be
  3982.           freely moved from one  computer location to  another, so long  as
  3983.           there is no  possibility of it  being used at one  location while
  3984.           it's being used at another.  Just as a book cannot be read by two
  3985.           different persons at the same time.
  3986.  
  3987.           Commercial users of CLOCK must register and pay for their  copies
  3988.           of  CLOCK within 30 days  of first use or  their license is with-
  3989.           drawn.    Site-License arrangements  may  be  made by  contacting
  3990.           Ronald Q. Smith.
  3991.  
  3992.           Anyone distributing CLOCK for any kind of remuneration must first
  3993.           contact Ronald Q. Smith at the address below for authorization.
  3994.  
  3995.           You are encouraged to pass a  copy of CLOCK along to your friends
  3996.           for evaluation.  Please encourage them to register their copy  if
  3997.           they  find that  they  can use  it.   All  registered users  will
  3998.           receive a copy of the latest version of the CLOCK system.
  3999.  
  4000.           Send the fees and any inquiries to:
  4001.  
  4002.                          Ronald Q. Smith
  4003.                          11 Black Oak Road
  4004.                          North Oaks, MN 55127-6204
  4005.  
  4006.           You may also contact me via CompuServe mail at userid  71620,514.
  4007.           I will be  happy to respond to  any problems and  suggestions for
  4008.           future capabilities.
  4009.  
  4010.           You may register CLOCK through the CompuServe Shareware Registra-
  4011.           tion program.  CLOCK.SYS is found under registration ID 104.  The
  4012.           fee for  registering through  CompuServe is  $12 (to  cover their
  4013.           charge) and will be added directly to your CompuServe bill.
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.                                           58
  4022.  
  4023.  
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.  
  4031.  
  4032.  
  4033.  
  4034.           CLOCK Version 3.44                                  March 9, 1993
  4035.  
  4036.  
  4037.           APPENDIX B:  CLOCK TYPES
  4038.  
  4039.  
  4040.           B.1  Type 0 - PC/AT
  4041.  
  4042.           IBM PC/AT and  all fully compatible  PCs.   Most versions of  DOS
  4043.           fully  support this  clock interface  without a  separate driver.
  4044.           Use CLOCK.SYS to provide support for CLK.EXE and CLKDEMO.EXE.  If
  4045.           you don't  need the  extra functions of  CLK, you  probably don't
  4046.           need CLOCK.SYS.  However,  there were a couple  of late 8088  PCs
  4047.           that adopted  the PC/AT  clock standard but  did not  provide the
  4048.           PC/AT recognition  sentinel.   DOS will not  find the  clock, but
  4049.           CLOCK.SYS will.
  4050.  
  4051.           Amstrad PC1521DD systems use this type of clock.
  4052.                           
  4053.           Automatic  determination checks  location F000:FFFE  for the  hex
  4054.           value FC.
  4055.  
  4056.           BIOS  calls are used to read and write the clock values which are
  4057.           usually stored  in the CMOS  RAM along  with other  configuration
  4058.           information.  The primary interfaces are:
  4059.                           
  4060.                Get Date: MOV  AH,4
  4061.                          INT  1AH
  4062.                               Returns the  year in CX and month  and day in
  4063.                               DX in  BCD format (e.g., a  hex display would
  4064.                               show:  CX=1991, DX=1009 for October 9, 1991).
  4065.  
  4066.                Set Date: MOV  AH,5
  4067.                               Load CX and DX as above for Get Date
  4068.                          INT  1AH
  4069.  
  4070.                Get Time: MOV  AH,2
  4071.                          INT  1AH
  4072.                               Returns hours  and minutes in CX  and seconds
  4073.                               in DH in BCD format.   May also return 100ths
  4074.                               of seconds in DL  (e.g., CX=2359, DX=5900 for
  4075.                               1 second before midnight).
  4076.  
  4077.                Set Time: MOV  AH,3
  4078.                               Load CX and DX as for Get Time
  4079.                          INT  1AH
  4080.  
  4081.  
  4082.  
  4083.  
  4084.  
  4085.  
  4086.  
  4087.                                           59
  4088.  
  4089.  
  4090.  
  4091.  
  4092.  
  4093.  
  4094.  
  4095.  
  4096.  
  4097.  
  4098.  
  4099.  
  4100.           CLOCK Version 3.44                                  March 9, 1993
  4101.  
  4102.  
  4103.           B.2  Type 1 - Zenith Z-18x portables, Supersport 20
  4104.  
  4105.           Automatic determination  checks location  F000:FFFA for  the two-
  4106.           byte hex value 4D32 ("M2").
  4107.  
  4108.           BIOS calls are used to read and write the clock.
  4109.  
  4110.                Get Date: MOV  AH,2
  4111.                          INT  1AH
  4112.                               Returns CX=year  (1980 - 2079) in  binary and
  4113.                               DH=month, DL=day.  All  values are binary.  A
  4114.                               hex display of the above date would look like
  4115.                               CX=7C7, DX=A09.
  4116.  
  4117.                Set Date: MOV  AH,3
  4118.                               Load CX and DX as for Get Date.
  4119.                          INT  1AH
  4120.  
  4121.                Get Time: MOV  AH,4
  4122.                          INT  1AH
  4123.                               Returns CH=hours, CL=minutes,  DH=seconds.  A
  4124.                               hex display would show: CX=173B, DX=3B00.
  4125.  
  4126.                Set Time: MOV  AH,5
  4127.                               Load CX and DX as for Get Time.
  4128.                          INT  1AH
  4129.  
  4130.  
  4131.           B.3  Type 2 - Various Zenith Data System PCs.
  4132.  
  4133.           Automatic  determination  looks  at location  F000:800A  for  the
  4134.           pattern 00,F0,"ZDS".
  4135.  
  4136.                Get Date: MOV  AH,2AH
  4137.                          INT  1AH
  4138.                               Returns CX and DX as for type 1.
  4139.  
  4140.                Set Date: MOV  AH,2BH
  4141.                               Load CX and DX as for type 1.
  4142.                          INT  1AH
  4143.  
  4144.                Get Time: MOV  AH,2CH
  4145.                          INT  1AH
  4146.                               Returns CX and DX as for type 1.
  4147.  
  4148.                Set Time: MOV  AH,2DH
  4149.                               Load CX and DX as for type 1.
  4150.                          INT  1AH
  4151.  
  4152.  
  4153.                                           60
  4154.  
  4155.  
  4156.  
  4157.  
  4158.  
  4159.  
  4160.  
  4161.  
  4162.  
  4163.  
  4164.  
  4165.  
  4166.           CLOCK Version 3.44                                  March 9, 1993
  4167.  
  4168.  
  4169.  
  4170.           B.4  Type 3 - Memory-Mapped Clocks
  4171.  
  4172.           Memory-mapped  clock used  on some  Zenith  Data Systems  PCs and
  4173.           other similar clocks including  many slot-less or no-slot clocks.
  4174.           The  SMT (Systems  Manufacturing Technology)  No-Slot  clocks are
  4175.           supported by this type.
  4176.  
  4177.           Automatic determination  is to  attempt to  read the  clock.   If
  4178.           values other than all 0FFH or  0 are obtained, this clock type is
  4179.           chosen.  All known segments and offsets are tried.
  4180.  
  4181.           Several  different memory  mapping approaches  are used  and many
  4182.           different  address possibilities  are  supported.   In general  a
  4183.           segment address in the ROM region (C800H through FFFFH) is  used.
  4184.           Offsets from that segment  address are used  to read bits,  write
  4185.           zero bits, and  write one bits.  Documentation  may specify those
  4186.           segments and  addresses in several  forms.  For  example, segment
  4187.           F000 with offset F002 is the same as segment FF00 with offset 2.
  4188.  
  4189.           Each memory reference reads  or writes a single bit.  Read opera-
  4190.           tions are  used  for all  references  with separate  offsets  for
  4191.           reading a bit, writing a zero bit, and writing a one bit.
  4192.  
  4193.           Clock segments and addresses currently probed include:
  4194.  
  4195.               ╔═══════╤═════════╤════════╤═════╤═════╤═════╤════════╗
  4196.               ║SEGMENT│WRITE 0  │WRITE 1 │READ │DECR │LAST │VENDOR  ║
  4197.               ╟───────┼─────────┼────────┼─────┼─────┼─────┼────────╢
  4198.               ║F000   │ F002    │F003    │F004 │0000 │F000 │(Zenith)║
  4199.               ╟───────┼─────────┼────────┼─────┼─────┼─────┼────────╢
  4200.               ║FE00   │    2    │   3    │   5 │0080 │C800 │SMT     ║
  4201.               ╟───────┼─────────┼────────┼─────┼─────┼─────┼────────╢
  4202.               ║FE00   │    0    │   2    │   8 │0080 │C800 │SMT     ║
  4203.               ╚═══════╧═════════╧════════╧═════╧═════╧═════╧════════╝
  4204.  
  4205.           Multiple address  combinations may be  tried for each  clock pat-
  4206.           tern.   The DECR value is  subtracted from the SEGMENT  value for
  4207.           another attempt  at probing  until the value  equals LAST.   Note
  4208.           that like  the SEGMENT address,  DECR and  LAST are  in units  of
  4209.           paragraphs (16-bytes).  Thus DECR of 80 is equivalent to 800H  or
  4210.           2048 bytes.
  4211.  
  4212.           When the  addresses used by a memory-mapped  clock are determined
  4213.           by  probing, the segment  and read address is  displayed.  As the
  4214.           read  address varies  the  most from  one  clock manufacturer  to
  4215.           another it is a good indication of the type of clock found.
  4216.  
  4217.  
  4218.  
  4219.                                           61
  4220.  
  4221.  
  4222.  
  4223.  
  4224.  
  4225.  
  4226.  
  4227.  
  4228.  
  4229.  
  4230.  
  4231.  
  4232.           CLOCK Version 3.44                                  March 9, 1993
  4233.  
  4234.  
  4235.           Data is stored in BCD in  bytes that you construct by shifting in
  4236.           the bits.  The most important data bytes are: 
  4237.                0 = Hundredths of seconds
  4238.                1 = Seconds
  4239.                2 = Minutes
  4240.                3 = hours
  4241.                5 = days
  4242.                6 = months
  4243.                7 = years mod 1980
  4244.  
  4245.  
  4246.           B.5  Type 4 - Direct Register I/O Bus Clock
  4247.  
  4248.           Many add-in clocks on  expansion boards use  this type of  clock.
  4249.           Some built-in clocks in  PCs are also  accessed similarly.   This
  4250.           clock was used on many AST  Research I/O boards for 8088 PCs such
  4251.           as  the Six-Pack Plus,  IO Plus,  etc.  Also  used on  some Tandy
  4252.           systems (e.g., 1200HD) and the Vendex Turbo-888-XT.
  4253.  
  4254.           Automatic determination is to attempt to read, complement, write,
  4255.           re-read, and re-complement one  of the registers.   If the  first
  4256.           value  read and the  re-complemented second value  are equal, the
  4257.           register exists and is presumed to be the clock.
  4258.  
  4259.           See also the description for types 6  and 7.  If you aren't  sure
  4260.           which variant you have, specify type 8 and automatic probing will
  4261.           determine if it  is really a type 4,  6, or 7.   For the greatest
  4262.           chance of detecting  the correct clock type, supply  the base I/O
  4263.           address if at all possible.
  4264.  
  4265.           NOTE:   If the clock is not correctly initialized (e.g., you have
  4266.           just replaced the  battery), CLOCK.SYS must initialize it so that
  4267.           the counters will  start working.  CLOCK.SYS  determines that the
  4268.           clock has been previously initialized by looking  at register 14H
  4269.           (see  B below).  If register B contains the value 0DEH, the clock
  4270.           is  presumed to be initialized.  If not, CLOCK.SYS will clear all
  4271.           the registers to zero and start the counters running.  While this
  4272.           form  of  checking for  initialization  was  commonly used,  your
  4273.           previous software may have  used a different method.  If  so, the
  4274.           first time  you run CLOCK.SYS  your date and  time may be  set to
  4275.           zero (1980-1-1 00:00:00).   If that happens, just  enter the date
  4276.           and time.  It should work OK after that without resetting to zero
  4277.           on further boots.
  4278.  
  4279.           Each clock register is implemented as a separate I/O register ad-
  4280.           dress.  Clock  base I/O addresses  of 240H, 2C0H, 300H,  and 340H
  4281.           are supported by automatic probing.  Similar clocks at other base
  4282.           I/O addresses  are supported  by specifying type  4 and  the base
  4283.  
  4284.  
  4285.                                           62
  4286.  
  4287.  
  4288.  
  4289.  
  4290.  
  4291.  
  4292.  
  4293.  
  4294.  
  4295.  
  4296.  
  4297.  
  4298.           CLOCK Version 3.44                                  March 9, 1993
  4299.  
  4300.  
  4301.           address.  The address range  used is the base  plus 0 through 1FH
  4302.           (e.g., 2C0H through 2DFH).
  4303.                           
  4304.           Important registers are (using 2C0 as the example):
  4305.                           
  4306.                2C1  =  100ths of seconds 
  4307.                2C2  =  seconds 
  4308.                2C3  =  minutes 
  4309.                2C4  =  hours 
  4310.                2C6  =  days
  4311.                2C7  =  months
  4312.                2C9  =  month last time clock was read/set 
  4313.                2CA  =  years
  4314.                2CB  =  initialized flag (0DEH if initialized)
  4315.                2D4  =  Status
  4316.                               
  4317.           All values are in BCD.  That means that each register consists of
  4318.           two 4-bit nybbles (a nybble is to a nibble as a byte is to a bite
  4319.           - I haven't seen this used recently,  but as a bit of trivia, the
  4320.           first IBM 360 principles of operation manuals used that term  and
  4321.           that spelling -  at least in a  draft copy that we got  in 1965).
  4322.           Each nybble contains  one decimal digit of the value.   Years are
  4323.           mod 1980 (i.e., 0 means 1980, 99 means 2079).
  4324.  
  4325.           Since these  clocks do not keep  the year and do  not handle leap
  4326.           years for you, CLOCK.SYS does the necessary calculations to  keep
  4327.           the year  correctly maintained  and to adjust  the date  for leap
  4328.           days.  The  clocks do  provide a  couple of  memory locations  in
  4329.           which CLOCK.SYS maintains  the year and previous month.   As long
  4330.           as you boot your system before a full year has passed,  CLOCK.SYS
  4331.           will correctly maintain the date.
  4332.  
  4333.  
  4334.           B.6  Type 5 - Mitsubishi 8088 PCs
  4335.  
  4336.           These were sold by Sperry as the PC-1 and  PC/HT, by Leading Edge
  4337.           as the Model D, by Mitsubishi, and others.
  4338.  
  4339.           Automatic  determination checks location F000:FFB3 for the string
  4340.           "MITSUBISHI".   Later Mitsubishi PCs which used a different clock
  4341.           had the same string  at a different location.  We  hope all early
  4342.           versions had it at this location.
  4343.  
  4344.  
  4345.  
  4346.  
  4347.  
  4348.  
  4349.  
  4350.  
  4351.                                           63
  4352.  
  4353.  
  4354.  
  4355.  
  4356.  
  4357.  
  4358.  
  4359.  
  4360.  
  4361.  
  4362.  
  4363.  
  4364.           CLOCK Version 3.44                                  March 9, 1993
  4365.  
  4366.  
  4367.           BIOS functions are used to access the clock.
  4368.  
  4369.                Get Date: MOV  AH,4
  4370.                          INT  1AH
  4371.                               Returns  CL=year  mod   1980,  DH=month,  and
  4372.                               DL=day all  in binary.  Also  sets AL=0FFH if
  4373.                               the clock  is busy and the  request should be
  4374.                               retried.
  4375.  
  4376.                Set Date: MOV  AH,5
  4377.                               Load CL, DX as for Get Date.
  4378.                          INT  1AH
  4379.                               Returns AL=0FFH if busy.
  4380.  
  4381.                Get Time: MOV  AH,2
  4382.                          INT  1AH
  4383.                               Returns  CH=hour,  CL=minute, DH=second,  and
  4384.                               AL=status.  AL=0FFH  means busy.   AL=0 means
  4385.                               24-hour mode.   AL=1 means AM  and AL=3 means
  4386.                               PM.
  4387.  
  4388.                Set Time: MOV  AH,3
  4389.                               Load AL, CX, DH as for Get Time.
  4390.                          INT  1AH
  4391.                               Returns AL=0FFH if busy.
  4392.  
  4393.           NOTE:  Some early Mitsubishi PCs came with fixed disk controllers
  4394.           that were not DOS compatible.  In addition to the clock modifica-
  4395.           tions, the DOS for those systems also handled the disk controller
  4396.           variant.  If you have such  a PC, CLOCK.SYS is not sufficient  to
  4397.           enable  you to go  above DOS  level 3.2.   You will  also need to
  4398.           replace your fixed disk controller.  I strongly suggest that  you
  4399.           create a boot floppy for your current DOS level before you try to
  4400.           install your new DOS level.  Then boot your new DOS from a floppy
  4401.           disk, do SYS C: and copy COMMAND.COM to C:, then try a disk boot.
  4402.           If the disk boot fails, boot the floppy you just created and do a
  4403.           SYS C:  and copy COMMAND.COM to  C: to restore your  old DOS ver-
  4404.           sion.  At that point, your best bet is to simply give up and stay
  4405.           with DOS 3.2. If you want to proceed, you must replace your fixed
  4406.           disk controller.
  4407.  
  4408.           If  SYS C:  gives you an  error status that  indicates that there
  4409.           isn't room  for the  new DOS version  (very possible  when moving
  4410.           from 3.2 to 3.3 or above), you must backup your entire fixed disk
  4411.           and use FORMAT C:/S to place the  new version of DOS on the disk.
  4412.           While  this is a hassle, at least if  your PC won't boot from the
  4413.           disk, the fall-back approach is identical.  There will be room to
  4414.           put DOS 3.2 or earlier back on the fixed disk.
  4415.  
  4416.  
  4417.                                           64
  4418.  
  4419.  
  4420.  
  4421.  
  4422.  
  4423.  
  4424.  
  4425.  
  4426.  
  4427.  
  4428.  
  4429.  
  4430.           CLOCK Version 3.44                                  March 9, 1993
  4431.  
  4432.  
  4433.  
  4434.           B.7  Type 6 - Indirect Register I/O Bus Clock
  4435.  
  4436.           Used on AST  Research boards and others.  Typically uses the same
  4437.           I/O base  address as  type 4.   However  the clock  registers are
  4438.           selected by sending the register address to the base I/O  address
  4439.           and then  reading or writing  data at the  base I/O address  + 1.
  4440.           The internal register numbers and their contents are the same  as
  4441.           for type 4.
  4442.  
  4443.           Automatic determination by probing the address  register.  If the
  4444.           low-order bit is one, it may be this type of clock or type 7.  We
  4445.           then look  further to determine if  it is type 7.   If you aren't
  4446.           sure which  type of clock you have but believe it is type 4, 6 or
  4447.           7, specify type 8 and automatic probing will detect which variant
  4448.           it  is.  If at all possible  specify the base I/O address as that
  4449.           will increase  the likelihood  that the correct  determination is
  4450.           made.
  4451.  
  4452.           I/O  addresses used  are (again  using  2C0 as  the example  base
  4453.           address):
  4454.  
  4455.                2C0    =  Address register.  Writing a value to this address
  4456.                          selects the internal register to read or write.
  4457.                2C1    =  Data register.   Reading or writing  this address,
  4458.                          reads or writes  the internal register  previously
  4459.                          selected by writing 2C0.
  4460.  
  4461.           The internal register numbers are (the values to write to 2C0):
  4462.  
  4463.                 1  =  100ths of seconds
  4464.                 2  =  seconds
  4465.                 3  =  minutes
  4466.                 4  =  hours
  4467.                 6  =  days
  4468.                 7  =  months
  4469.                 9  =  month last time date was read or written
  4470.                 A  =  year
  4471.                 B  =  initialization flag
  4472.                14  =  status
  4473.                           
  4474.           Other processing is the same as type 4.
  4475.  
  4476.  
  4477.  
  4478.  
  4479.  
  4480.  
  4481.  
  4482.  
  4483.                                           65
  4484.  
  4485.  
  4486.  
  4487.  
  4488.  
  4489.  
  4490.  
  4491.  
  4492.  
  4493.  
  4494.  
  4495.  
  4496.           CLOCK Version 3.44                                  March 9, 1993
  4497.  
  4498.  
  4499.           B.8  Type 7 - Complex I/O Bus Clock
  4500.  
  4501.           Used  on AST Research boards and others.  Typically uses the same
  4502.           base I/O address as  types 4 and 6.   Type 7 uses a more  complex
  4503.           register  access sequence than type 6.  Type 7 can be detected by
  4504.           looking to see if the value in register D has bit 1 (value=2) set
  4505.           which type  6 will not.  If  you aren't sure which  type of clock
  4506.           you have  but believe it is  type 4, 6  or 7, specify type  8 and
  4507.           automatic  probing will  detect which variant  it is.   If at all
  4508.           possible specify the  base I/O address as that  will increase the
  4509.           likelihood that the correct determination is made.
  4510.  
  4511.           The base I/O address is used  as an address register and the base
  4512.           + 1 as  a data register.  This  is the same as for  clock type 6.
  4513.           However, the internal  registers and the form of  the commands is
  4514.           quite  different.  The  primary difference  is that  the internal
  4515.           registers only hold four  bits of data each.  Thus  each internal
  4516.           register represents a single decimal digit.
  4517.  
  4518.           The I/O addresses are used as follows (using 2C0 as an example):
  4519.  
  4520.                2C0     = Address register.  The  number of an internal reg-
  4521.                          ister  plus 80H is written  to this I/O address to
  4522.                          select an internal register.
  4523.  
  4524.                2C1     = Data register.   Four  bits  of data  are read  or
  4525.                          written  using this  I/O  address from  or to  the
  4526.                          internal register  previously selected  by writing
  4527.                          to 2C0.
  4528.  
  4529.           The internal registers are:
  4530.  
  4531.                0  =  Units digit of seconds
  4532.                1  =  Tens digit of seconds
  4533.                2  =  Units digit of minutes
  4534.                3  =  Tens digit of minutes
  4535.                4  =  Units digit of hours
  4536.                5  =  Tens digit of hours
  4537.                6  =  Day of week
  4538.                7  =  Units digit of day of month
  4539.                8  =  Tens digit of day of month
  4540.                9  =  Units digit of month
  4541.                A  =  Tens digit of month
  4542.                B  =  Units digit of year
  4543.                C  =  Tens digit of year
  4544.                D  =  Function register
  4545.                E  =  Function register
  4546.                F  =  Function register
  4547.  
  4548.  
  4549.                                           66
  4550.  
  4551.  
  4552.  
  4553.  
  4554.  
  4555.  
  4556.  
  4557.  
  4558.  
  4559.  
  4560.  
  4561.  
  4562.           CLOCK Version 3.44                                  March 9, 1993
  4563.  
  4564.  
  4565.  
  4566.           B.9  Type 8 - Generic I/O Bus Clock
  4567.  
  4568.           Type unknown.  Probe only for types 4, 6, 7, 9, and B.   Use type
  4569.           8 if you are sure that you have an I/O bus clock (i.e., the clock
  4570.           is on an add-in card) but aren't sure whether it is type 4, 6, 7,
  4571.           9, or  B.  If at all possible, supply the base I/O address of the
  4572.           clock as this will greatly increase the likelihood of the correct
  4573.           handling method being chosen.
  4574.  
  4575.  
  4576.           B.10 Type 9 - Quadram I/O Bus Clock
  4577.  
  4578.           This type  was  used  by Quadram  Corporation  on  the  QuadCard,
  4579.           QuadCard II, and QuadCard 512+.  It may have  been used on others
  4580.           as well.
  4581.  
  4582.           Automatic determination checks to see that I/O registers exist at
  4583.           310H or 210H.
  4584.  
  4585.           This clock  used four I/O  control registers and  twelve internal
  4586.           registers.  The I/O registers (using 310H as the example) are:
  4587.  
  4588.                310  =  Data register (used to move data values)
  4589.                311  =  Address register (used to select internal register)
  4590.                312  =  Function register (Read, write, hold counter)
  4591.                313  =  Control register (Enables read or write function)
  4592.  
  4593.  
  4594.  
  4595.  
  4596.  
  4597.  
  4598.  
  4599.  
  4600.  
  4601.  
  4602.  
  4603.  
  4604.  
  4605.  
  4606.  
  4607.  
  4608.  
  4609.  
  4610.  
  4611.  
  4612.  
  4613.  
  4614.  
  4615.                                           67
  4616.  
  4617.  
  4618.  
  4619.  
  4620.  
  4621.  
  4622.  
  4623.  
  4624.  
  4625.  
  4626.  
  4627.  
  4628.           CLOCK Version 3.44                                  March 9, 1993
  4629.  
  4630.  
  4631.           The internal registers are:
  4632.  
  4633.                 0 = Units digit of seconds
  4634.                 1 = Tens digit of seconds
  4635.                 2 = Units digit of minutes
  4636.                 3 = Tens digit of minutes
  4637.                 4 = Units digit of hours
  4638.                 5 = Tens digit of hours - Also uses bit 2 (=4) to  indicate
  4639.                     PM if  in 12-hour mode and bit 3 (=8) to select 24-hour
  4640.                     mode
  4641.                 6 = Day of week (we don't use this)
  4642.                 7 = Units digit of days
  4643.                 8 = Tens digit  of days - Also uses  bit 3 (=8) to indicate
  4644.                     that  this is a  leap year.   This bit  must be  set by
  4645.                     software whenever there is less than 366 days until the
  4646.                     next leap day.  If you  do not boot within that period,
  4647.                     leap day will not be taken.
  4648.                 9 = Units digit of months
  4649.                10 = Tens digit of months
  4650.                11 = Units digit of year mod 1980
  4651.                12 = Tens digit of year mod 1980
  4652.  
  4653.           NOTE:  If you have this type of clock, you  can only set the time
  4654.           to the nearest minute.  Whenever the time is set, the seconds are
  4655.           always  set to  zero.   You  should set  the time  as the  minute
  4656.           changes.  For that reason, you will not want to use the automatic
  4657.           adjustment capability of  CLK with this type of clock  as it will
  4658.           try to set the time to the nearest second.
  4659.  
  4660.  
  4661.           B.11 Type A - AT&T 6300, 6300 PLUS, 6300 WGS
  4662.  
  4663.           Automatic probing  is accomplished by  trying to read  the clock.
  4664.           If the read attempt using the BIOS is  successful (carry flag not
  4665.           set) and the values returned look like a valid time, the clock is
  4666.           assumed to be present.
  4667.  
  4668.           NOTE:  AT&T clocks  do not advance the year on January  1.  It is
  4669.           necessary  to change  the date  at  the beginning  of each  year.
  4670.           Also, AT&T clocks always clear the seconds to zero  when the time
  4671.           is changed.  For  this reason you should always set  the date and
  4672.           time  at the beginning of a minute.   You should also not use the
  4673.           automatic adjustment feature of CLK with these clocks.
  4674.  
  4675.           A base year may be specified on the DEVICE= line.  If it is  not,
  4676.           1992 will be  used.  This  base will be  good for all dates  from
  4677.           1992-1-1 till 1999-12-31.
  4678.  
  4679.  
  4680.  
  4681.                                           68
  4682.  
  4683.  
  4684.  
  4685.  
  4686.  
  4687.  
  4688.  
  4689.  
  4690.  
  4691.  
  4692.  
  4693.  
  4694.           CLOCK Version 3.44                                  March 9, 1993
  4695.  
  4696.  
  4697.           BIOS functions are used with this clock.
  4698.  
  4699.                Get Date: MOV  AH,0FEH
  4700.                          INT  1AH
  4701.                               Returns BX =  Days since base, CH = Hours, CL
  4702.                               = Minutes, DH = Seconds,  DL = 100ths of sec-
  4703.                               onds
  4704.  
  4705.                Set Date: MOV  AH,0FFH
  4706.                          MOV  BX,Days since base
  4707.                          MOV  CH,Hours
  4708.                          MOV  CL,Minutes
  4709.                          MOV  DH,0
  4710.                          MOV  DL,0
  4711.                          INT  1AH
  4712.  
  4713.  
  4714.           B.12 Type B - Hyundai 8088 clock
  4715.  
  4716.           Automatic determination  probes the control registers.   If they,
  4717.           appear to be present, CLOCK tries to read the  clock.  Legal time
  4718.           and date values will select this clock.
  4719.  
  4720.           This clock uses I/O addresses E0H through EFH as follows:
  4721.                E0  =  Units digit of seconds
  4722.                E1  =  Tens digit of seconds
  4723.                E2  =  Units digit of minutes
  4724.                E3  =  Tens digit of minutes
  4725.                E4  =  Units digit of hours
  4726.                E5  =  Tens digit of hours
  4727.                E6  =  Day of week
  4728.                E7  =  Units digit of days
  4729.                E8  =  Tens digit of days
  4730.                E9  =  Units digit of month
  4731.                EA  =  Tens digit of month
  4732.                EB  =  Units digit of year
  4733.                EC  =  Tens digit of year
  4734.                ED  =  Control
  4735.                EE  =  Control
  4736.                EF  =  Control
  4737.  
  4738.  
  4739.  
  4740.  
  4741.  
  4742.  
  4743.  
  4744.  
  4745.  
  4746.  
  4747.                                           69
  4748.  
  4749.  
  4750.  
  4751.  
  4752.  
  4753.  
  4754.  
  4755.  
  4756.  
  4757.  
  4758.  
  4759.  
  4760.           CLOCK Version 3.44                                  March 9, 1993
  4761.  
  4762.  
  4763.           APPENDIX C:  REVISION HISTORY
  4764.  
  4765.           930309 -  Version 3.44: Modified M= to automatically set the date
  4766.                     and time on the L= to the same as the last M= if the L=
  4767.                     is  earlier.  It also  sets any remaining adjustment to
  4768.                     zero.  This  is because the clock  was adjusted exactly
  4769.                     at the point represented by the M=.
  4770.  
  4771.           930306 -  Version 3.43:  Fixed bug with M= function not forcing a
  4772.                     read of the  A= functions in CLK.INI and  thus not cor-
  4773.                     rectly displaying the previous and new adjustment.
  4774.  
  4775.           930304 -  Version 3.42:  Changed time  moving backwards logic  to
  4776.                     only look  for earlier  hours.  At  least one  case has
  4777.                     been seen of a program that set the time backward a few
  4778.                     ticks by  direct  calls on  the  BIOS and  resulted  in
  4779.                     CLOCK.SYS advanceing the day.  Now we only advance  the
  4780.                     day if the time moves backwards an hour or  more.  Also
  4781.                     added the /N  option for CLOCK.SYS that  shuts off this
  4782.                     logic  completely  if the  date  advances unexpectedly.
  4783.                     Also fixed a bug in locating the CLK.INI file when  the
  4784.                     A= function is used by itself.
  4785.  
  4786.           930220 -  Version 3.41: Changed timing window prevention logic in
  4787.                     CLOCK.SYS to  control another possible case  of the day
  4788.                     advancing twice over midnight.
  4789.  
  4790.           930212 -  Version 3.40:  Added the M=  function and /M  option to
  4791.                     provide calculation  of the  adjmustment value.   Added
  4792.                     help for all functions and options. Added the /B option
  4793.                     in anticipation  of later support of  full-screen mode.
  4794.                     Added the ,C  flag on  the /I and  /M options to  allow
  4795.                     updating a  read-only file.   Added error  messages for
  4796.                     I/O errors when updating the file.  Fixed timing window
  4797.                     in  CLOCK.SYS  that  could  occur  when the  continuous
  4798.                     display  is operational  that could  cause the  date to
  4799.                     advance unpredictably.
  4800.  
  4801.           930204 -  Version 3.31:  Fixed bug  in CLOCK.SYS with  some clock
  4802.                     types  causing system  lockups or  bad  data to  be re-
  4803.                     turned.
  4804.  
  4805.           930130 -  Version  3.30: Added  support  for a  password and  for
  4806.                     saving  the current  CLOCK.SYS state as  a new  copy of
  4807.                     CLOCK.SYS for  future booting.   Added  continuous time
  4808.                     display.   Changed  API  to support  direct calls  from
  4809.                     BASIC,  FORTRAN,  and Pascal  as  well as  C  and MASM.
  4810.                     Changed status display to be easier to read.
  4811.  
  4812.  
  4813.                                           70
  4814.  
  4815.  
  4816.  
  4817.  
  4818.  
  4819.  
  4820.  
  4821.  
  4822.  
  4823.  
  4824.  
  4825.  
  4826.           CLOCK Version 3.44                                  March 9, 1993
  4827.  
  4828.  
  4829.           930115 -  Version 3.24: Converted document to WordPerfect 5.1 and
  4830.                     rewrote  much  of it.    Provide  document in  standard
  4831.                     release that can either be viewed on-line or printed.
  4832.  
  4833.           930110 -  Version  3.23: Added  support for  R= and  W= commands.
  4834.                     Fixed handling of CLK.INI file so that we don't try  to
  4835.                     update  it if  it  is read  only or  is in  a read-only
  4836.                     sub-directory.   We  also don't update  it if  we can't
  4837.                     find the  [clk] section  as it  may  be someone  else's
  4838.                     file.
  4839.  
  4840.           930106 -  Version 3.22:  Fixed bug in  CLK.EXE that caused  it to
  4841.                     move the CLK.INI file to the root directory.
  4842.  
  4843.           930104 -  Version 3.21: Fixed bug in CLOCK.SYS expecting zero for
  4844.                     100ths of seconds from CMOS clock but  some BIOSs don't
  4845.                     zero the register.  Fixed bug in CLK with  synchroniza-
  4846.                     tion algorithm not correctly waiting for a new second.
  4847.  
  4848.           930102 -  Version 3.20:  Add support for a command file, automat-
  4849.                     ic adjustment, and improved synchronization.  My thanks
  4850.                     to Eric Smith for the ideas that lead to these enhance-
  4851.                     ments.
  4852.  
  4853.           921230 -  Version 3.11:  Simplified logic in CLOCK.SYS for check-
  4854.                     ing if calendar clock should be read.
  4855.  
  4856.           921229 -  Version 3.10: Add  support for constant synchronization
  4857.                     with calendar clock.  Fix bug in calculating dates near
  4858.                     the end of leap years.
  4859.  
  4860.           921226 -  Version 3.02: Recompile CLK.EXE and CLKDEMO.EXE to only
  4861.                     use 8088 instructions.  Version 3.01 inadvertently com-
  4862.                     piled with  80286 instructions  which can lock  up 8088
  4863.                     systems.
  4864.  
  4865.           921221 -  Version  3.01: Fixed  a  couple of  bugs  in beta  test
  4866.                     version 3.00 with non-PC/AT clocks.  Added logic to CLK
  4867.                     to  display the  pre-defined  time zones  on errors  or
  4868.                     request.
  4869.  
  4870.           921219 -  Version 3.00: Added support for automatic time zone and
  4871.                     daylight savings  time adjustment.   CLOCK.SYS  now has
  4872.                     the ability to  manage the DOS real time  clock and the
  4873.                     battery-protected clock separately.  CLK.EXE is used to
  4874.                     convert a base value  in the battery-protected clock to
  4875.                     a correct local time in the DOS clock.
  4876.  
  4877.  
  4878.  
  4879.                                           71
  4880.  
  4881.  
  4882.  
  4883.  
  4884.  
  4885.  
  4886.  
  4887.  
  4888.  
  4889.  
  4890.  
  4891.  
  4892.           CLOCK Version 3.44                                  March 9, 1993
  4893.  
  4894.  
  4895.           920614 -  Version 2.24: Fixed bug in probing of AT&T 6300 clocks.
  4896.                     Some of the  clocks do not set AL  on successful opera-
  4897.                     tion.
  4898.  
  4899.           920604 -  Version  2.23:  Fixed  bug  causing fall  through  into
  4900.                     memory probing when only I/O probing was wanted.
  4901.  
  4902.           920411 -  Version 2.22: Changed order of probing to probe memory-
  4903.                     mapped clocks  last as they are  being spuriously found
  4904.                     on some Tandy systems.
  4905.  
  4906.           920401 -  Version 2.21:   Changed pattern of  I/O address probing
  4907.                     to probe all possible I/O addresses for one type (e.g.,
  4908.                     4) before trying any  for another type.   Try to  avoid
  4909.                     finding the wrong  type.  Added the type B clock to the
  4910.                     type 8 probe.
  4911.  
  4912.           920328 -  Version 2.20:  Changed order of I/O address probing for
  4913.                     clock  types 4,  6,  and 7  to  avoid, where  possible,
  4914.                     accessing other  boards.  Most commonly  used I/O clock
  4915.                     addresses, I hope, are now probed first.
  4916.  
  4917.           920322 -  Version 2.19:  Improved probing for I/O clocks to check
  4918.                     that legal values are found  in all the data registers.
  4919.                     Several of  the I/O  clocks use operation  sequences so
  4920.                     much like each other that it is possible to choose  the
  4921.                     wrong one if  we don't actually read the  time and date
  4922.                     and see  if the  values are  legal.   This approach  to
  4923.                     probing may possibly result in not finding a clock that
  4924.                     is present  but that  has been totally  reset.   Such a
  4925.                     clock should  be found  on a  second try  to boot  with
  4926.                     CLOCK.SYS as the counters will have advanced by then.
  4927.  
  4928.           920320 -  Version  2.18:   Added probing  for generic  PC/AT type
  4929.                     clock on systems that don't have the PC/AT signature in
  4930.                     the BIOS.
  4931.  
  4932.           920307 -  Version 2.17:  Added Hyundai 8088 clock.
  4933.  
  4934.           920112 -  Version 2.16:  Added AT&T 6300 clock.
  4935.  
  4936.           920111 -  Version 2.15:  Fixed memory address used by one type of
  4937.                     SMT No-Slot clock.
  4938.  
  4939.           920105 -  Version  2.14:   Added support  for a wider  variety of
  4940.                     memory mapped clocks  including the SMT  (Systems Manu-
  4941.                     facturing Technology) No-Slot clocks.
  4942.  
  4943.  
  4944.  
  4945.                                           72
  4946.  
  4947.  
  4948.  
  4949.  
  4950.  
  4951.  
  4952.  
  4953.  
  4954.  
  4955.  
  4956.  
  4957.  
  4958.           CLOCK Version 3.44                                  March 9, 1993
  4959.  
  4960.  
  4961.           911208 -  Version 2.13:  Add  probing for Vendex Headstart Turbo-
  4962.                     888-XT system and any other I/O clock at 300H.   Change
  4963.                     I/O clock probing logic to make it less likely to  find
  4964.                     the wrong type by accident.
  4965.  
  4966.           911129 -  Version 2.12:  Fix handling of Quadram clocks (type 9).
  4967.                     They can only set seconds to zero so generate an  error
  4968.                     if anyone tries to set the seconds to any other value.
  4969.  
  4970.           911128 -  Version  2.11:   Fix  bug  in  handling clock  type  9,
  4971.                     Quadram clocks that left  clock turned off after opera-
  4972.                     tions.   Also fix bug  in busy determination  for clock
  4973.                     types 4 and 6 that could result in a decision  that the
  4974.                     clock was not operational.
  4975.  
  4976.           911121 -  Version 2.10:  Add  clock types 6 ,7 and 9.  Add type 8
  4977.                     to do specific  probing for the  various I/O bus  clock
  4978.                     types.
  4979.  
  4980.           911109 -  Version 2.05:   Fix  bug in leap  day handling  for I/O
  4981.                     clocks.  Fix bug that caused hung systems  when setting
  4982.                     the date or time on Z-18x portables.
  4983.  
  4984.           911026 -  Version 2.04:  Add support  for I/O clocks at addresses
  4985.                     240H  and 340H.    Reduce resident  memory required  by
  4986.                     clock driver  to only that required  for specific clock
  4987.                     type.
  4988.  
  4989.           911021 -  Version 2.03:   Change handling  of new  day flag  from
  4990.                     BIOS to  accommodate BIOSs that  indicate multiple days
  4991.                     have passed.
  4992.  
  4993.           911020 -  Version 2.02:  Fix bug in returning date on clock  read
  4994.                     functions.  Added message in automatic determination to
  4995.                     indicate type found.
  4996.  
  4997.           911010  - Version  2.01:     Added  automatic   determination  of
  4998.                     Mitsubishi 8088 PC clocks.   Fixed handler to  keep the
  4999.                     BIOS  counter set  properly for  programs that  read it
  5000.                     directly.    Also  returns  a finer  granularity  value
  5001.                     (100ths of seconds) on reads.
  5002.  
  5003.           911009  - Version 2.00:   Modified clock driver  to support addi-
  5004.                     tional clock types.  Thanks to Eric Smith (no relation)
  5005.                     for help in finding out how the Zenith PC clock worked.
  5006.  
  5007.           911005  - Version 1.20:  Changed prologue and epilogue to conform
  5008.                     to DOS 5.00  documentation.  Seems to work  OK with DOS
  5009.  
  5010.  
  5011.                                           73
  5012.  
  5013.  
  5014.  
  5015.  
  5016.  
  5017.  
  5018.  
  5019.  
  5020.  
  5021.  
  5022.  
  5023.  
  5024.           CLOCK Version 3.44                                  March 9, 1993
  5025.  
  5026.  
  5027.                     5.0 without the  changes, but we might as  well be con-
  5028.                     sistent to save problems later.
  5029.  
  5030.           910903  - Version 1.10:   Added display of current date  and time
  5031.                     when initializing.
  5032.  
  5033.           910518  - CLOCK version  1.00.  Initial version  developed at the
  5034.                     request of a  friend with a Sperry PC/HT  who wanted to
  5035.                     move to DOS 4.01.
  5036.  
  5037.           1984    - Write clock device driver  for AST clock for  IBM PC-1.
  5038.                     This serves as the  introduction to what device drivers
  5039.                     and especially the CLOCK$ driver are all about.
  5040.  
  5041.  
  5042.  
  5043.  
  5044.  
  5045.  
  5046.  
  5047.  
  5048.  
  5049.  
  5050.  
  5051.  
  5052.  
  5053.  
  5054.  
  5055.  
  5056.  
  5057.  
  5058.  
  5059.  
  5060.  
  5061.  
  5062.  
  5063.  
  5064.  
  5065.  
  5066.  
  5067.  
  5068.  
  5069.  
  5070.  
  5071.  
  5072.  
  5073.  
  5074.  
  5075.  
  5076.  
  5077.                                           74
  5078.  
  5079.  
  5080.  
  5081.  
  5082.  
  5083.